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Foreword 



The PL/I system is a complete software package for both applications and system 
programming. PL/I runs under the Digital Research single-user operating systems, 
CP/M® or CP/M-86®. PL/I runs in a multiuser environment, under MP/M II™, 
or MP/M-86™. This manual assumes you are familiar with your operating system and 
minimizes references to it. 

PL/I is formally based on the Subset G language defined by the ANSI PL/I Stan- 
dardization Committee X3J1. Subset G contains all the necessary application pro- 
gramming constructs of full PL/I, and discards seldom-used or redundant forms. The 
resulting language encourages good programming practices while simplifying the com- 
pilation task. 

The PL/ 1 Language Programming Guide is divided into three parts. The first part, 
Sections 1 through 6, presents a brief introduction to the PL/I language, with emphasis 
on block structure, data types, and its various executable statements. Section 5 gives 
guidelines for developing a readable programming style. Section 6 explains the oper- 
ation of the system as a whole, and introduces you to the mechanics of compiling, 
linking, and executing programs. 

The second part, Sections 7 through 16, contains detailed sample programs that 
illustrate the useful facilities of the language, including Input/Output processing, string 
and list processing, scientific computation, and business applications. Each section 
presents general concepts, and then a detailed discussion of one or more example 
programs to illustrate the concepts. 

The third part, Section 17 through 20, presents advanced programming topics, such as 
the internal representation of data, conventions for interfacing assembly language 
programs with PL/I modules, making direct operating system calls, and writing PL/I 
programs that use overlays. 

The best way to learn any programming language is to study working examples. To 
learn PL/I, you should study these example programs along with the associated text, 
and cross-check the material with the PL/ 1 Language Reference Manual when necessary. 
Once you understand the operation of a particular program, you can modify the 
program to enhance its operation and further your experience with the language. 
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Section 1 
Introduction 



1.1 WhatisPL/I? 

PL/I is a programming language that you can use to write either applications or 
system-level programs. It is formally based on the ANSI General Purpose Subset (Subset 
G) as specified by the ANSI PL/I Standardization Committee X3J1. PL/I Subset G has 
the formal structure of the full language, but in some ways it is a new language, and 
in many ways an improved language compared to its parent. 

PL/I Subset G is easy to learn and use. It is a highly portable language because its 
design generally ensures hardware independence. It is also more efficient and cost 
effective, because programs written in PL/I Subset G are easier to implement, document, 
and maintain. 



1.2 Using This Manual 

This manual is designed to help you learn PL/I by studying sample programs. If you 
have never programmed in a structured, high-level language such as PL/I, you should 
read Sections 1 through 4 first. These sections provide you with a brief introduction 
to the language. PL/I has features that are similar to other programming languages, 
but it also has its own unique constructs and syntax. 

Sections 1 through 4 outline the fundamental structure and features of PL/I in an 
informal and conceptual framework. This summary can help you become familiar with 
the overall capabilities of PL/I and encourage you to use its full power. 

Sections 1 through 4 are not a complete tutorial on PL/I programming in general. 
If you find the overview is not sufficiently detailed, you might want to read some of 
the books listed in Appendix E of the PL/I Language Reference Manual. You should 
also refer to the material in Sections 1 through 4 of the PL/I Language Reference 
Manual. 

If you are already an experienced PL/I programmer, you might want to begin with 
Section 6, which describes how to compile and link programs. 



1.3 Notation PL/I Programming Guide 

1.3 Notation 

The following notational conventions appear throughout this document: 

■ Words in capital letters are PL/I keywords or the names of PL/I programs that 
are described in the text. 

■ Words in lower-case letters or in a combination of lower-case letters and digits 
separated by a hyphen represent variable information for you to select. These 
words are described or defined more explicitly in the text. 

■ Example statements are given in lower-case. 

■ The vertical bar | indicates alternatives. 

■ ^ represents a blank character. 

■ Square brackets [ ] enclose options. 

■ Ellipses . . . indicate that the immediately preceding item can occur once or any 
number of times in succession. 

■ Except for the special characters listed above, all other punctuation and special 
characters represent the actual occurrence of those characters. 

■ In text, the symbol CTRL represents a control character. Thus, CTRL-C means 
control-C. In a PL/I source program listing or any listing that shows example 
console interaction, the symbol A represents a control character. 

■ The acronym BIF refers to one of the PL/I built-in functions. 

■ Throughout this manual, program listings have brackets on the left side to 
illustrate and emphasize the block structure of the language. 

■ References to material in the PL/I Language Reference Manual are noted at the 
end of each section. The acronym LRM denotes Language Reference Manual. 
For example, 

References: LRM Section 3.1.1 

End of Section 1 
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Section 2 
The PL/I Language 

Every PL/I program consists of one or more statements from three general categories: 

■ structural statements 

■ declarative statements 

■ executable statements 

These categories are not mutually exclusive, but provide a convenient starting point. 
The following sections describe and illustrate the statements in each general category. 

2.1 Structural Statements 

Structural statements are the foundation of any program because they define the 
logical units in a program. These logical units are called blocks. When a program 
executes, control always flows from one logical unit to another. Logical units can 
contain other logical units, causing control to flow into and out of the units. You use 
structural statements to specify the hierarchical and logical structure in a program. 

2.2 Declarative Statements 

Declarative statements always occur in a logical unit defined by a structural statement, 
and determine the environment of a logical unit. The environment is the name and 
type of all the data variables available in a logical unit. Use declarative statements to 
specify the context of the variables you want to manipulate in a logical unit. 

2.3 Executable Statements 

Executable statements manipulate storage, transfer the flow of control between log- 
ical units, control the flow of data to and from I/O devices, and perform calculations. 
Both structural statements and declarative statements serve only to create a context 
for executable statements. 
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Listing 2-1 shows a PL/I program that illustrates statements from each category. You 
need not fully understand the program or the syntax of each statement at this point. The 
program consists of distinct blocks of statements; each block is a logical unit of control. 



sample 



procedure opt i ons ( main ) 5 
declare 

c characte r ( 10) varviM! 

-do » 

put sKip list(*Input: ')! 
Set 1 ist ( c ) i 

c = upper(c)! /* function reference */ 
put sKip 1 ist ( 'Output : '»c)i 
end ! 

■beSin 5 
declare 

c float binary (24) 5 

put sKip list( ' Input: ' ) I 
Set listtc ) i 

call output(c)! /* subroutine invocation */ 
end ! 



procedure(c) returns ( characte r( 10) uaryinS); 
declare 

c characte r( 10) varyinsi 

return( translated » v ABCDEFGHI JKLMNOPQRSTUUWXYZ ' , 
'abcdefg'hiJKlmnopqrstuuwxyz')) > 
— end uppe r 5 

-output: 

procedure ( c ) 5 
declare 

c float binary (24) i 

put skip edit(c) ( column (20) »e ( 10 >2) ) i 
end output! 



I — end sample i 



Listing 2-1. SAMPLE PL/I Program 
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Every PL/I program must have a main procedure block. Although you can separately 
develop and compile external procedures that can be linked to and called from a main 
procedure, there can be only one main procedure block in a program. In Listing 2-1, 
the first two statements, together with the last statement, determine the outermost, or 
main block of the program. 

2.4 PL/I Blocks 

In PL/I a block can have its own local environment, and possibly an environment 
inherited from a containing block. A containing block is any block that contains another 
block. For example, in Listing 2-1 the DO-group inherits the environment of the main 
procedure block. However, the BEGIN block has its own local environment, even 
though it is contained in the main procedure block. 

In PL/I there are two types of blocks: 

■ PROCEDURE blocks 

■ BEGIN blocks 

You can nest either type of block. This means that you can put one block inside 
another, but the blocks cannot overlap. The essential difference between a PROCE- 
DURE block and a BEGIN block is the way that PL/I executes each block in the overall 
program. 

PL/I executes BEGIN blocks as they are encountered in the normal sequence of 
statements in the program. A BEGIN block ends when its corresponding END statement 
is encountered or when control passes outside the block. When control reaches a BEGIN 
block, the statements inside the block execute sequentially. Usually, when control leaves 
the block, it simply passes to a containing block or goes to the next sequential block. 
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PL/I ignores PROCEDURE blocks as they are encountered in the usual sequence of 
statements in the program. Control only passes to and enters a PROCEDURE block 
when the program invokes the procedure with a CALL statement or a function ref- 
erence. A PROCEDURE block is active when the statements inside the block are / 
executing. When the statements inside the procedure finish executing, the PROCEDURE \ 
block returns control to the point of the call. 

For this reason, you can place a procedure anywhere in a program. It is good 
programming practice to put all procedures at the bottom of the main program. This 
makes debugging and maintaining a program easier. 



2.5 Procedures 

Every procedure consists of a procedure name, procedure header, the procedure body 
of zero or more statements, and an end statement. Figure 2-1 shows the components 
of the main procedure in the SAMPLE program. 

procedure name 7 procedure header - 



sample: 

procedure options(main) 



procedure body 



end sample; - 
end statement 



Figure 2-1. PL/I Procedure Components 
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If you nest procedures, they inherit the environment of containing blocks. However, 
any variable that you declare in a containing block can be redeclared, with local 
attributes, in the nested procedure. 

There are two general types of procedures in PL/I: 

■ subroutine procedures 

■ function procedures 

Use the CALL statement to invoke a subroutine procedure. A subroutine procedure 
performs a specific task, and optionally returns values to the invoking procedure. 

Invoke a function procedure by making a function reference. A function reference 
is simply using the name of the function in a statement. PL/I evaluates the function 
reference and replaces it with a scalar value at the point of the reference. 

Procedures are either internal or external in relation to the main procedure. An 
internal procedure is contained in the body of the main procedure, while external 
procedures are written and compiled separately from the main program. To make an 
external procedure known to the main procedure, you must declare the procedure name 
as an entry constant (see Section 3.1.3). You must also link the external procedure to 
the main procedure after both are compiled. All the procedures in the SAMPLE program 
are internal to the main procedure. 



2.6 DO-groups 

The DO-group is similar to the BEGIN block. There are several forms of the DO- 
group, and they are executable statements because they influence the flow of control. 
However, they are also considered structural statements because they define logical 
units. 

Listing 2-1 illustrates the simplest form of the DO-group. It looks like a BEGIN 
block, but there is a crucial difference. Although a DO-group binds all the statements 
in its body into one logical unit, it cannot define a new environment. A DO-group 
cannot define new variables whose environment is limited to the body of the DO- 
group. 
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A DO-group can bind only executable statements. However, a BEGIN block can 
bind both declarative statements and executable statements. The environment of a DO- 
group is determined by the environment of the block where it occurs. 

End of Section 2 



ILL INFORMATION PRESENTED HERE IS PROPRIETARY TO DIGITAL RESEARCH 



Section 3 
Declarations 



Use declarative statements to specify the data items you want to manipulate with 
the executable statements in your program. PL/I has a rich variety of data types. In 
addition to arithmetic and string data, PL/I supports pointer, label, and entry data, 
which are generally not available in other languages. Table 3-1 shows the PL/I data 
types divided into categories and subcategories. 

Table 3-1. PL/I Data Types 



Category 


Subcategory 


Arithmetic 


FIXED BINARY 
FLOAT BINARY 
FIXED DECIMAL 


String 


CHARACTER 
BIT 


Control 


Label Variable 
Label Constant 
Entry Variable 
Entry Constant 


Pointer 


POINTER 


File 


File Variable 
File Constant 




Data Aggregates 


Arrays 
Structures 




Procedures 


Subroutines 
Functions 
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All declarative statements specify either data constants or data variables. You must 
explicitly declare all data variables in a DECLARE statement, but data constants are 
usually declared implicitly by their occurrence in an executable statement. A PL/I 
variable is defined by an identifier name. The name can consist of up to thirty-one 
alphanumeric characters or underscores. The first character must be a letter. 

Usually, declarative statements, whether explicit or implicit, result in a specific allo- 
cation of storage for the data item declared. The Compiler determines the amount of 
storage required for the type of data, and associates the item with this storage. BASED 
variables are an exception because they do not necessarily force an allocation of storage 
(see Section 4.5). 



3.1 Scalar Data 

There are two main kinds of data: scalar, or single, data items, and aggregate, or 
multiple, data items. Scalar data types are the fundamental data types of the language. 

3.1.1 Arithmetic Data 

You use arithmetic data for direct numerical calculation. PL/I provides several types 
of arithmetic data, so you can match the data to the application. 

FIXED BINARY 

You can use FIXED BINARY data to represent integers. PL/I internally represents 
this data type in two's complement binary form. The precision of a FIXED BINARY 
number is the number of bits used to represent it, independent of the sign. PL/I uses from 
1 to 15 bits, so it can represent integers in the range from -32768 to +32767. 

FLOAT BINARY 

You can use FLOAT BINARY data to represent very small or very large numbers. 
FLOAT BINARY data has a binary fractional part (called the mantissa), a binary 
exponent, and a sign. PL/I supports both single-precision and double-precision FLOAT 
BINARY numbers. The precision of a FLOAT BINARY number is the number of bits 
in the mantissa. 

Single-precision numbers can have from 1 to 24 bits, while the exponent part is 
always represented by 8 bits. The maximum range of single-precision FLOAT BINARY 
numbers in decimal is approximately 5.88 * 10**-39 to 3.40 * 10**38. 
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Double-precision numbers can have from 24 to 53 bits, while the exponent has 1 1 bits. 
The maximum range of double-precision FLOAT BINARY numbers in decimal is 
approximately 9.40 * 10**- 308 to 1.80 * 10**308. 

FIXED DECIMAL 

You can use FIXED DECIMAL data to represent numbers with a fixed decimal 
point. You can also use FIXED DECIMAL data to represent integers. Internally, 
PL/I represents FIXED DECIMAL data in binary coded decimal (BCD) digits. 

FIXED DECIMAL numbers have both precision and scale. The precision is the total 
number of decimal digits used to represent the number. The scale is the number of 
decimal digits to the right of the decimal point. 

In PL/I, the precision of a FIXED DECIMAL number can vary from one to fifteen, 
while the scale can vary from zero to fifteen. This arithmetic data type is particularly 
useful for commercial calculations, which require exact representations of dollars and 
cents and cannot accept the truncation errors of binary arithmetic. 

You declare an arithmetic data variable in a declaration statement of one of the 
following forms, where p is the precision and q is the scale. 

Statement: 

DECLARE identifier FIXED BINARY[(p)]; 
Example: 

declare i n d e x_c o u n t e r fixed b i n a r y ( 7 ) 5 
Statement: 

DECLARE identifier FLOAT BINARY[(p)]; 
Example: 

declare pi float binary (53)5 
Statement: 

DECLARE identifier FIXED DECIMAL[(p[,q])]; 
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Example: 

declare base_pav fixed dec imal ( 5 t 2 ) 5 

Note: precision and scale are optional. If you omit them, PL/I supplies default values. 

You should use binary arithmetic for most numerical work, because it is faster and 
uses the least storage. If you are doing scientific work, PL/I has a complete library of 
built-in mathematical functions, which includes the trigonometric and the hyperbolic 
functions. 

3.1.2 String Data 

The ability to manipulate string variables is one of the most useful features of 
PL/I. PL/I has a complete set of built-in functions that you can use to manipulate string 
data. You declare a string variable to be either a bit string or a character string in a 
declaration of one of the following forms: 

Statement: 

DECLARE identifier CHARACTER^)]; 

Example: 

declare alphabet character(2G)5 
Statement: 

DECLARE identifier CHARACTER[(n)] VARYING; 
Example: 

declare state cha rac t e r ( 20 ) varying? 
Statement: 

DECLARE identifier BIT[(n)] ; 
Example: 

declare flag b i t ( 1 ) 5 
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The VARYING attribute means that the character string can vary in length, but 
cannot exceed the value of n. For CHARACTER variables, the value of n can be 
between and 254. If you want to manipulate longer strings, you can use one-dimen- 
sional arrays. 

Character-string constants are implicitly declared by their occurrence in a program. 
Indicate a character-string constant by enclosing it in apostrophes. If you want to 
include an apostrophe in the string, you must precede it with an extra apostrophe. 
PL/I also allows you to include control characters in a character string. 

The following are examples of character strings: 

'Ada Louelace' 

v '" sf "3 Input Error' 

x C a n ' ' t Read Previous Line" 

Bit-string variables cannot have the VARYING attribute, and the length of a bit 
string cannot exceed sixteen. PL/I allows you to specify bit-string constants in several 
different formats. Each format corresponds to a different base, which is the number 
of bits used to represent the item. The formats for bit-string constants are: 

■ base 2 (B or Bl format) 

■ base 4 (B2 format) 

■ base 8 (B3 format) 

■ base 16 (B4 format) 

In each of the formats, write the bit-string constant as a string of numeric digits for 
the desired base, enclosed in apostrophes and followed by the format type. The fol- 
lowing are examples of the four formats: 



x 1 1 1 1 1 ' B 


equals 


101111 


x 1 1 1 1 1 ' B 1 


equals 


101111 


x 233 'B2 


equals 


101111 


X 57'B3 


equals 


101111 


X 2F'B4 


equals 


1011 
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3.1.3 Control Data 

There are two types of control data: 

■ LABEL data 

■ ENTRY data 
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LABEL data allows you to reference individual statements in your program. PL/I 
not only allows individual statements to have labels, it also allows you to declare label 
variables. This means that you can manipulate labels in your program like any other 
valid data items. 

The value of a label variable is always a label constant, implicitly defined and declared 
by its occurrence as a label of a statement in the program. PL/I allows you to subscript 
label constants. You can also declare arrays of label variables. 

You can use label variables to manipulate the flow of control between logical units of 
a program. It is better programming practice to do this without using GOTOs and 
labels. 

The following program is a whimsical example of label variables. 

chase_y on r_t ai 1 : 

procedure options(wain) 5 
declare 

wherever label? 

there: 

wherever = here! 
here: 

wherever = there? 
Soto wherever! 

end chase_y ou r_t ai 1 5 

PL/I also supports a powerful data type called ENTRY data. ENTRY data allows 
you to reference procedures just like any valid data item. You can declare an entry 
variable then assign it a value. The value of an entry variable is an entry constant. 

Entry constants are the labels of procedures, rather than labels of executable state- 
ments. An entry constant is implicitly declared by its appearance as a label to an 
internal procedure. 

When you declare an entry variable, you must explicitly define the type of entry 
constant that the variable can assume. When you explicitly declare an entry constant, 
you must declare it with the same attributes as the procedure it references. 
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The programs shown in Listing 3-1 illustrate these concepts. Listing 3- la shows an 
external procedure called a. Listing 3-lb shows the program CALL, that references a. 
In CALL, f is an entry variable that assumes three different constant values. To create 
an executable program, you compile each module separately then link them together. 



procedure(x) retums(float)! / * external procedure */ 
declare x float) 
retu rn ( x/2 ) i 
end a i 

Listing 3-la. External Procedure A 

call: 

procedure options(main) 5 
declare 

f ( 3 ) entry (float) returns(float) variable) 
a entry (float) retums(float)! /* entry constant /* 
declare 

i fixed f x float! 

f (1) = a5 
f(2) = bi 
f (3) = c i 

do i = 1 to 3 5 

put skip list('Type x ' ) 5 

Set list (x) i 

put 1 ist ( "f ( ' ,i , ') = ' if (i) (x) ) ; 
end 5 
stop i 

b: 

procedure (x) retu rns ( f 1 oat ) 5 /* internal procedure */ 

declare x float? 

return (2*x +1)5 
end b ! 



procedure(x) retu rns ( float ) 5 /* internal procedure */ 
declare x float? 
ret u rn ( s in ( x ) ) 5 
1 — end c 5 

1 — end call? 

Listing 3-lb. The CALL Program 

. - ;\ .-..,■. 15 
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3.1.4 Pointer Data 

Pointer data allows you to manipulate the storage allocated to variables. The value 
of a pointer variable is the address of another variable. 

3.1.5 File Data 

File data items describe and provide access to the data associated with an external 
device. File data items are either file constants or variables. You must always assign a 
file constant to a file variable before you access the data in the file. 

Declare file data in a declaration statement in one of the following forms: 

Statement: 

DECLARE identifier FILE; 

Example: 

declare c u r r e n t_t r a n s a c t i o n file! 

Statement: 

DECLARE identifier FILE VARIABLE; 
Example: 

declare f(2) file variable? 

The executable statements used for file access determine the file attributes. (Section 
4.3 describes file-handling and I/O operations.) 

3.2 Data Aggregates 

A data aggregate is a combination of data types that forms a data type on a higher 
level. There are two kinds of aggregates in PL/I: 

■ arrays 

■ structures 
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3.2.1 Arrays 

An array is a subscripted collection of data items of the same data type. PL/I allows 
arrays of arithmetic values, character strings, bit strings, label constants, entry con- 
stants, pointers, files, or structures (see Section 3.2.2). 

The following are examples of array declarations: 

declare t e s t_s c o r e s ( 1 ) 5 

declare A(4 *5) ; 

declare A ( 1 : 4 > 2 : 5 1 : 1 ) 5 

You make direct references to individual elements of an array by using a subscripted 
variable reference. PL/I also allows you to make cross-sectional references, with the 
restriction that the reference must specify a data component whose storage is connected. 
For example, using the following declarations, 

declare A ( 5 > 2 ) fixed binary! 
declare B ( 5 > 2 ) fixed binary; 
you can visualize the arrays pictured in Figure 3-1: 





A 

1 2 


1 
2 
3 
4 
5 


B 

1 2 


1 






2 






3 






4 




5 







Figure 3-1. Arrays 
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In this example, A and B are identical in size and attributes. Therefore, an assignment 
such as 

a ( 3 ) = b ( a ) ; 

is valid because the cross-sectional reference specifies connected storage. 

3.2.2 Structures 

A structure is a very different type of data aggregate than an array. A structure is 
hierarchical, much like a tree, where the leaves of the tree, called nodes, can be various 
PL/I data types. 

Each node of the tree, beginning with the root, has a name and a level number. The 
level number indicates the level of each node in relation to the root. The following 
example illustrates a structure declaration. 

declare 

1 employee* 

2 name_add res s * 
3 n awe > 

4 first character(iO) » 
4 mi d d 1 e_ initial character(l) t 
4 last cha racte r ( 20 ) > 
3 address* 

4 street character(40)> 
4 city character(lO)* 
4 state cha racte r ( 2 ) » 
4 zip_code character(5) » 
2 position* 

3 d e p a r t m e n t_^n o character(3)» 
3 Job_title character(20)* 
2 salary fixed decimal(8»2)> 
2 n u ffl'b e r_o f _d e p e n d e n t s fixed* 
2 heal th_p Ian bi t ( 1 ) > 
2 date hired character(8) ! 
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Figure 3-2 illustrates the hierarchy of levels that corresponds to the declaration. 



employeer 



-name address- 



-name- 



first 

middle_initial 

last 



address 




position- 



department_no 
• job_title 



1 salary 

number_of_dependents 
healthplan 
date_hired 

Figure 3-2. Structure Declaration Hierarchy 

Nodes on each level can also determine a structure. Such a substructure is a member 
of the main structure. You can give the BASED attribute to the main structure with 
the result that all the members of the structure receive the attribute. 

Structures are powerful tools because they enable you to group logically related data 
items that might not have the same data type. Thus, structures allow you to characterize 
and manipulate logical objects in your program to more closely resemble real data. 



End of Section 3 
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Section 4 
Executable Statements 



The category of executable statements is divided into several subcategories based on 
the type of function that the statement performs. The subcategories are: 

■ assignment statements 

■ sequence control statements 

■ I/O and file-handling statements 

■ memory management statements 

■ condition processing statements 

■ preprocessor statements 

■ null statements 



4.1 Assignment Statements 

An assignment statement places the value of an expression into the storage location 
associated with a variable. 

An expression is a combination of operators, operands, function references, and 
parentheses that control the order of evaluation of the expression. 

In PL/I, the assignment statement has the form: 

variable reference = expression; 
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An expression in PL/I can be fairly complicated. The simplest type of variable ref- 
erence is instantiating the variable name, which means to assign the variable a specific 
value. A variable reference can also be a reference to a data aggregate, or to a component 
of the aggregate. If the variable is BASED, a pointer-qualified reference might be 
required (see Section 4.5.1). 

PL/I also allows certain built-in functions such as UNSPEC and SUBSTR to appear 
as targets on the left side of assignment statements. When they appear as variables in 
this context, they are called pseudo-variables. 

Expressions can be computational. This means that the expression involves arithmetic 
or string values of the various types and their respective operators. Expressions can 
also be noncomputational, involving comparisons of noncomputational data types such 
as labels, entry constants, and pointers. 

PL/I allows computational expressions of different data types, and automatically 
performs conversion between the various types following a standard set of default rules. 
You should become familiar with the automatic conversion rules and the properties 
of the built-in conversion functions (see Section 4 LRM). 
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The following sequence of code illustrates some simple examples of assignment 
statements. These examples also illustrate some of the ways you can reference a variable 
in PL/I. Such references can also occur in expressions, although PL/I limits aggregate 
expressions to comparison for equality. 

-assign: 

procedure o p t i o n s ( m a i n ) i 
declare 

p pointer* 

i fixed b i n a r y ( 7 ) i 

r b i t ( 1 6 ) * 

s bit (IB) based » 

(u iv) float binary (24) > 

A(5 *2) characte r(2) * 

B(5 )2) character(2) , 

C character(20) > 

1 w I 

2 x fixed binary* 
2 v b i t ( 1 G ) . 



1 



2 x fixed binary* 
2 y bit (IB) !■ 



u = u + Mi / * simple assignment * / 

A = B 5 /* array a^SreSate assignment */ 

A ( 3 ) = B(4)i /* cross-sectional reference */ 

w = zi /* structure aSSrea'ate assignment */ 

p - > s = ( r = w . y ) ! /* pointer-qualified reference * / 

w.x = w.x + z.xi /* partially-qualified aSSreSate reference */ 

unspec(w.y) - unspec ( A ( 5 * 1 ) ) i /# pseudo-variable reference */ 

subst r (C >i + l *3) = subst r ( C * 10 *3 ) i /* pseudo- va r i abl e reference */ 

A(2*i + 1) = B ( 4 ) ; /* ua ri able is expression */ 



— end ass i 3n 5 

4.2 Sequence Control Statements 

You can use sequence control statements to alter the normal sequential flow of 
control. In PL/I, sequence control statements perform unconditional branching, con- 
ditional branching, iteration, branch and return through procedure invocation, and a 
more unique construct called condition processing. 
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4.2.1 iteration 

PL/I provides an extensive variety of iteration control in the various forms of the 
DO statement. For example, you can perform iteration not only with an arithmetic 
control variable, but also with a pointer control variable that is moving through a 
linked list of pointers. 

The following diagrams illustrate the basic forms of the DO statement and the flow 
of control mat they induce. The values el, e2, e3, and e4 represent any scalar expressions. 



DO; 



END; 



DO WHILE(e); 



END; 




DO i = el REPEAT (e2); 



END; 







' 


' 






i=el 








■ 


' 




1. 






' 


' 








i=e2 






' 


' 





Figure 4-1. Forms of the DO Statement 
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DO i = el REPEAT(e2) WHILE(e3); 



END; 



DO i = el TO e2 BY e3 WHlLE(e4); 



END; 




Figure 4-1. (continued) 
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4.2.2 Procedure Invocation 

A branch and return occurs as the result of a procedure invocation. As we have seen, 
in PL/I there are two types of procedures: subroutine procedures and function pro- 
cedures. There are two corresponding forms of invocation. 

You invoke a subroutine procedure with a CALL statement, but you invoke a function 
procedure by using its name in an expression. You call a subroutine procedure for a 
specific reason, such as altering the value of variables passed to the procedure, or input 
and output. You always invoke a function procedure in an expression to return a scalar 
data item. In PL/I, both types of procedures can be recursive, which means they can call 
themselves. 

There is an important distinction between a procedure definition and a procedure 
invocation. A procedure definition is a declarative statement; a procedure invocation 
is an executable statement. The data items you pass to the procedure when you invoke 
it are called the actual parameters. The actual parameters are distinguished from the 
formal parameters you give in the procedure definition. Thus, the actual parameters 
are the parameters as they are known in the invoking block, while the formal parameters 
are the corresponding parameters as they are known in the invoked block, the procedure. 

4.2.3 Parameter Passing 

In PL/I, you can pass parameters by reference or by value. You pass them by reference 
if the actual parameters and the formal parameters share storage. You pass them by 
value if the value of the formal parameter is held as a local copy of the value of the 
actual parameter. 

Under PL/I rules, the formal parameter and actual parameter always share storage 
if they have identical attributes. If the actual parameter is an expression, or if its data 
attributes do not match those of the corresponding formal parameter, then the param- 
eter is passed by value. PL/I passes the parameter by value if you enclose the formal 
parameter in parentheses in the procedure header statement of the procedure definition. 
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A procedure is an independent logical unit that performs a specific function. If you 
carefully define the specific function that the procedure performs and the parameters 
that it expects from the invoking environment, you can divide the design, coding, and 
debugging of the overall program into separate units. 

If you pass a parameter by reference to conserve storage, be aware that the invoked 
procedure can change the value of a variable outside its local environment. If you want 
to assure that the procedure does not change a variable outside its local environment, 
then you must pass the parameters by value and use extra storage. 

Parameter passing is a trade-off between the amount of storage available on your 
system and the level of modularity and isolation you want in your program. There are 
three alternatives for parameter passing, characterized as the high, middle, and low 
road. The skeletal program in Listing 4-1 illustrates the concepts they represent. 

In the low road, you pass by reference but pay close attention to the possible side 
effects that can result. The advantage of this method is that it conserves storage. 

In the middle road, you pass by value, enclosing the actual parameter in parentheses 
at the point of invocation in the CALL statement or function reference. 

In the high road, you declare a duplicate variable for each formal parameter in the 
procedure definition. You then assign the corresponding formal parameter to its dupli- 
cate, and use the duplicate as a local copy in the procedure. Equally you can enclose 
the formal parameter in parentheses in the procedure header. The high road is least 
efficient in its use of storage. 
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, — wain : 

procedure options(wain)! 
declare 

a float binary? 



call low_sub(a)5 /* pass by reference */ 
call middle_sub ( ( a) ) ! /* pass by value */ 
call hish sub(a)i /* pass by reference */ 



low_5ub : 

procedure(x) 5 
declare 

x float binary! 



I — end low_sub 5 

mi d d 1 e_s ub : 

procedure(x)5 
declare 

x float binary? 



— end middl e_sub 5 

hi sh_sub : 

procedure(x) i 
declare 

( x tfny_x ) f 1 oat binary 5 
my x = x5 /* reassign usins local variable */ 



1 — end hi sh_sub 5 
end Main! 



Listing 4-1. Parameter Passing 
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4.2.4 Conditional Branch 

PL/I provides a conditional branch in the form of an IF statement. The conditional 
branch has one of the following forms, 

IF condition THEN group 

IF condition THEN group- 1 ELSE group-2 

where the condition is a scalar expression that PL/I evaluates and reduces to a single 
value, and the groups are either single statements, DO-groups, or BEGIN blocks. 

You can nest IF statements, in which case PL/I matches each ELSE with the innermost 
unmatched IF-THEN pair. However, you can use NULL statements following an ELSE 
to force an arbitrary matching of ELSE statements with IF-THEN pairs. (See Section 
4.7 NULL Statements.) 

4.2.5 Unconditional Branch 

PL/I provides an unconditional branch in the form of a GOTO statement. The 
unconditional branch has one of the following forms: 

GOTO label_constant; 
GOTO label_variable; 

Because PL/I is block-structured, certain rules apply to the use of the GOTO. The 
target label must be in the same block containing the GOTO, or in a containing block. 
You cannot transfer control to an inner block. 



4.3 I/O and File-handling Statements 

The executable I/O statements provide PL/I with a device-independent input/output 
system that allows a program to transmit data between memory and external devices. 
To understand the I/O statements, you must first know about files and their attributes. 

The collection of data elements that you transmit to or from an external device is 
called the data set. The corresponding internal file constant or variable is called a file. 
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As with other data items, you must declare files before you use them in a program. 
The general form of a file declaration is, 

DECLARE file_id FILE [VARIABLE]; 

where file_id is the file identifier. If you do not include the optional VARIABLE attrib- 
ute, the declaration defines a file constant. With the VARIABLE attribute, the decla- 
ration defines a file variable that can take on the value of a file constant through an 
assignment statement. You must assign a file constant to a file variable before you can 
perform any I/O operations. 

4.3.1 Opening Files 

PL/I requires that a file be open before performing any I/O operations on the data 
set. You can open a file explicitly by using the OPEN statement, or implicitly by 
accessing the file with the following I/O statements: 

■ GET EDIT 

■ PUT EDIT 

■ GET LIST 

■ PUT LIST 

■ READ 

■ WRITE 

■ READ Varying 

■ WRITE Varying 

The general form of the OPEN statement is, 

OPEN FILE(file_id) [file-attributes]; 

where file_id is the file identifier that appears in a FILE declaration statement, and file- 
attributes denotes one or more of the following: 

■ STREAM | RECORD ■ TITLE 

■ PRINT ■ ENVIRONMENT 

■ INPUT | OUTPUT | UPDATE ■ PAGESIZE 

■ SEQUENTIAL | DIRECT ■ LINESIZE 

■ KEYED 
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Multiple attributes on the same line are conflicting attributes, so you can only specify 
one attribute. The first attribute listed is the default attribute. All the attributes are 
optional; you can specify them in any order. 

A STREAM file contains variable length ASCII data. You can visualize it as a stream 
of ASCII character data, organized into lines and pages. Each line in a STREAM file 
is determined by a linemark, which is a line-feed or a carriage return/line-feed pair. 
Each page is determined by a pagemark, which is a form-feed. Generally, you must 
convert the data in a STREAM file from character form to pure binary form before 
using it. ED automatically inserts a line-feed following each carriage return, but files 
that PL/I creates can contain line-feeds without preceding carriage returns. In this case, 
PL/I senses the end of the line when it encounters the line-feed. 

A RECORD file contains binary data. PL/I accesses the data in blocks determined 
by a declared record size, or by the size of the data item you use to access the file. A 
RECORD file must also have the KEYED attribute, if you use FIXED BINARY keys 
to directly access the fixed-length records. 

The PRINT attribute applies only to STREAM OUTPUT files. PRINT indicates that 
the data is for output on a line printer. 

For an INPUT file, PL/I assumes that the file already exists when it executes the 
OPEN statement. When it executes the OPEN statement for an OUTPUT file, PL/I 
also creates the file. If the file already exists, PL/I first deletes it, then creates a new 
one. 

You can read from and write to an UPDATE file. PL/I creates an UPDATE file, if it 
does not exist, when executing the OPEN statement. An UPDATE file cannot have the 
STREAM attribute. 

You access SEQUENTIAL files sequentially from beginning to end, but you access 
DIRECT files randomly using keys. PL/I automatically gives DIRECT files the RECORD 
attribute. PL/I also requires you to declare all UPDATE files with the DIRECT attribute, 
so you can locate the individual records. 
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A KEYED file is simply a fixed-length record file. The key is the relative record 
position of the record within the file based upon the fixed record size. You must use 
keys to access a KEYED file. PL/I automatically gives KEYED files the RECORD 
attribute. 

The TITLE(c) attribute defines the programmatic connection between an internal 
filename and an external device or a file in the operating system's file system. If you 
omit the TITLE attribute, PL/I assigns the default title file_id.DAT, where file_id is 
the file identifier specified in the OPEN statement. 

If the character string c specifies a disk file, it must be in the form, 

d : filename.typ ;password 

where the drive code d, the filetype, and the password are all optional. You must specify 
a filename. The filename cannot be an ambiguous wildcard reference. 

You can also specify $1 or $2 for both the filename and filetype. $1 gets the first 
default name from the command line, $2 gets the second default name. 

The ENVIRONMENT attribute defines fixed record sizes for RECORD files, internal 
buffer sizes, the file open mode, and the level of password protection. You can open 
a file in one of three modes: Locked, Read-Only, or Shared. Locked is the default 
mode, and means that no other user can access the file while it is open. Read-Only 
means that other users can access the file, but only to read it. Shared mode means that 
other users can also simultaneously open and access the file. You can use the built-in 
LOCK and UNLOCK functions to lock and unlock individual records in the file, so 
there are no collisions with other users. 

If you assign a password to a file, you can also assign the level of protection that 
the password provides. The levels of protection are: Read, Write, and Delete. Read 
means that you must supply the password to read the file. Write means that you can 
read the file, but you must supply the password to write to the file. Delete means that 
you can read the file or write to it, but you cannot delete the file without the password. 

The LINESIZE attribute applies only to STREAM files, and defines the maximum 
number of characters in the input or output line length. The PAGESIZE attribute 
applies only to STREAM OUTPUT files, and defines the number of lines per page on 
output. 
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4.3.2 File Attributes 

PL/I controls all file transactions through an internal data structure called the File 
Parameter Block (FPB). The FPB contains information about the file, such as whether 
it is open or closed, the external device or file associated with the file, the current line 
and column, or record being accessed, and the internal buffer size. The FPB also contains 
a File Descriptor that describes the file's attributes. These attributes in turn describe 
the allowable methods of access. Table 4-1 summarizes the valid attributes that you 
can assign to a file, either through an explicit OPEN statement, or implicitly by an 
I/O access statement. 





Table 4-1. PL/I Valid File Attributes 


STREAM 


INPUT 


ENVIRONMENT TITLE LINESIZE 


STREAM 


OUTPUT 


ENVIRONMENT TITLE LINESIZE PAGESIZE 


STREAM 


OUTPUT PRINT ENVIRONMENT TITLE LINESIZE PAGESIZE 




RECORD 


INPUT 


SEQUENTIAL 


ENVIRONMENT TITLE 


RECORD 


OUTPUT 


SEQUENTIAL 


ENVIRONMENT TITLE 




RECORD 


INPUT 


SEQUENTIAL 


KEYED ENVIRONMENT TITLE 


RECORD 


OUTPUT 


SEQUENTIAL 


KEYED ENVIRONMENT TITLE 


RECORD 


INPUT 


DIRECT 


KEYED ENVIRONMENT TITLE 




RECORD 


OUTPUT 


DIRECT 


KEYED ENVIRONMENT TITLE 


RECORD 


UPDATE 


DIRECT 


KEYED ENVIRONMENT TITLE 
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4.3.3 Implied Attributes 

If you do not open a file with explicit attributes, PL/I determines the attributes from 
the type of I/O statement you use to access the file. Table 4-2 summarizes the attributes 
implied by each of the I/O statements. In the following table, f is a file constant, x is 
scalar or aggregate data type that is not CHARACTER VARYING, and k is a FIXED 
BINARY key value. 

Table 4-2. File Attributes Associated With I/O Access 



I/O Statement 


Implied Attributes 


GET FILE(f) LIST 


STREAM INPUT 


PUT FILE(f) LIST 


STREAM OUTPUT 


GET FILE(f) EDIT 


STREAM INPUT 


PUT FILE(f) EDIT 


STREAM OUTPUT 


READ FILE(f) INTO(v) 


STREAM INPUT 


WRITE FILE(f) FROM(v) 


STREAM OUTPUT 


READ FILE(f) INTO(x) 


RECORD INPUT SEQUENTIAL 


READ FILE(f) INTO(x) KEYTO(k) 


RECORD INPUT SEQUENTIAL KEYED 

ENVIRONMENT(Locked,Fixed(i)) 


READ FILE(f) INTO(x) KEY(k) 


RECORD INPUT DIRECT KEYED 
ENVIRONMENT(Locked,Fixed(i)) 




RECORD UPDATE DIRECT KEYED 

ENVIRONMENT(Locked,Fixed(i)) 


WRITE FILE(f) FROM(x) 


RECORD OUTPUT SEQUENTIAL 


WRITE FILE(f) FROM(x) KEYFROM(k) 


RECORD OUTPUT DIRECT KEYED 
ENVIRONMENT(Locked,Fixed(i)) 




RECORD UPDATE DIRECT KEYED 
ENVIRONMENT(Locked,Fixed(i)) 
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4.3.4 Closing Files 

The CLOSE statement disassociates the file from the external data set. The form of 
the CLOSE statement is, 

CLOSE FILE(file_id); 

where file_id is a file constant for which PL/I clears the internal buffers, records all 
the data on the disk, and closes the file at the operating system level. You can subse- 
quently reopen the same file using the OPEN statement. PL/I automatically closes all 
open files at the end of the program or upon execution of a STOP statement. 

4.3.5 File Access Methods 

PL/I supports two methods of file access: 

■ STREAM I/O 

■ RECORD I/O 

There are three different kinds of STREAM I/O: 

■ LIST-directed uses the GET LIST and PUT LIST statements, which transfer a list 
of data items without any format specifications. 

■ Line-directed uses the READ and WRITE statements, which allow you to access 
variable-length CHARACTER data in an unedited form. These statements might 
not be available in other implementations of PL/I. 

■ EDIT-directed uses the GET EDIT and PUT EDIT statements, which allow 
formatted access to character data items. 

EDIT-directed I/O is similar to list-directed I/O except that it writes data into 
particular fields of the output line, as described by a list of format items. The data list 
specifies a number of values to write in fixed fields defined by the format list. 

The format list can contain two kinds of format items : data format items and control 
format items. PL/I pairs each element of the data list with a data format item in the 
format list. The format item determines how PL/I interprets the data element. PL/I 
executes control format items as they are encountered in the format list. 
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You can precede any format item with a positive constant integer value, not exceeding 
254, that determines the number of times to apply the format item or group of format 
items. 

4.3.6 Data Format Items 

The following examples show the various format items you can use in a GET EDIT 
or PUT EDIT statement. 

A[(w)] 

The A format reads or writes the next alphanumeric field whose width is specified 
by w, with truncation or blank padding on the right. If you omit w, the A format uses 
the size of the converted character data as a field width. 

B[n][(w)] 

The B format reads or writes bit-string values, n is the number of bits used to repre- 
sent each digit, w is the field width that you must include on input. 

E(w[,d]) 

The E format reads or writes a data item into a field of w characters in scientific 
notation, with maximum precision allowed in the field width, w must be at least 8. 

F(w[,d]) 

The F format reads or writes fixed-point arithmetic values with a field width of w 
digits, and d optional digits to the right of the decimal point. 

4.3.7 Control Format Items 

LINE(ln) 

Moves to the line In in the data stream before writing the next data item. 

COLUMN(nc) 

Moves to column position nc in the data stream before reading or writing the next 
data item. This can flush the current line. 
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PAGE 
Performs a page eject for PRINT files. 

SKIP[(nl)] 
Skips nl lines before reading or writing the next data item. 

X(n) 

Advances n blank characters into the data stream before reading or writing the next 
data item. 

R(fmt) 

Specifies a remote format. This means that the format is specified elsewhere in a 
FORMAT statement. 

4.3.8 Predefined Files 

PL/I has two predefined file constants called SYSIN, the console keyboard, and 
SYSPRINT, the console output display. These files do not need to be declared unless 
you make an explicit reference to them in an OPEN or I/O statement. 

SYSIN has the default attributes: 

STREAM INPUT ENVIRONMENT < Locked »Buff < 128 ) ) TI TLE ( x $C0N ' ) 
LINESIZE(80) PAGESIZE(O) 

SYSPRINT has the default attributes: 

STREAM PRINT ENVIRONMENT (Locked *Buff < 128 > ) TI TLE ( v $CON ' ) 
LINESIZE(80) PAGESIZE(O) 



4.4 Condition-processing Statements 

PL/I has several features that make it ideal for applications programming. One of 
these features is its capability for condition processing. In most languages, the program 
cannot recover from run-time error conditions, such as an invalid data conversion — 
control reverts to the operating system. 
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Because PL/I is designed as a production-programming language, it has various 
features that allow you to intercept run-time errors, program a response, and recover 
control. These features are collectively called condition processing. 

PL/I provides condition processing with these executable statements: 

■ ON 

■ REVERT 

■ SIGNAL 

4.4.1 The ON Statement 

Use the ON statement to intercept and program a response to a run-time condition 
signaled by the system, or by the execution of a SIGNAL statement. The ON statement 
is an executable statement that defines the response. It has the form, 

ON condition on-body; 

where condition is one of the major condition categories, with or without a subcode 
(see Section 4.4.4). The on-body is a PL/I statement or statement group that you process 
when the condition occurs. 

If the subcode is not present, then PL/I processes the ON statement when any of the 
subcode conditions occur. This is equivalent to subcode 0. The file conditions must 
have a file reference describing the file for which the condition is signaled. 

4.4.2 The REVERT Statement 

Use the REVERT statement to disable the ON condition set by the ON statement. 
This is important because you can have only sixteen ON conditions set without over- 
flowing the condition code area. If overflow happens, the PL/I run-time system stops 
processing. The form of the REVERT statement is: 

REVERT condition; 

PL/I automatically reverts an ON condition set in a given block when control leaves 
the environment of that block. 
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4.4.3 The SIGNAL Statement 

The SIGNAL statement allows you to activate the response for a condition. The 
form of the SIGNAL statement is: 

SIGNAL condition; 

4.4.4 Condition Categories 

The condition categories describe the various conditions that the run-time system 
can signal or that your program can signal by executing a SIGNAL statement. 

There are nine major condition categories with subcodes, some of which are system- 
defined, and some of which you can define yourself. Table 4-3 shows the predefined 
subcodes. 



Table 4-3. 


PL/I Condition Categories and Subcodes 


Type 


Meaning 


ERROR 




ERROR(O) 


Any ERROR subcode 


ERROR( 1 ) 


Data conversion 


ERROR (2) 


I/O Stack overflow 


ERRORO) 


Function argument invalid 


ERR0R(4) 


I/O Conflict 


ERROR (5) 


Format stack overflow 


ERROR(G) 


Invalid format item 


ERROR (7) 


Free space exhausted 


ERR0R(8) 


Overlay error, no file 


ERRORO) 


Overlay error, invalid drive 


ERROR ( 10) 


Overlay error, size 


ERROR ( 11 ) 


Overlay error, nesting 


ERROR ( 12) 


Overlay error, disk read error 


ERR0R( 13) 


Invalid OS call 


.ERR0R( 14) 


Unsuccessful Write 


ERROR ( 15) 


File Not Open 


ERR0R( 16) 


File Not Keyed 
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Table 4-3. 


(continued) 


Type 


Meaning 


FIXEDOVERFLOW 

FIXEDOVERFLOW(O) 


Any FIXEDOVERFLOW subcode 


OVERFLOW 

OVERFLOW (0) 
OVERFLOW ( 1 ) 
OVERFLOW(Z) 


Any OVERFLOW subcode 
Floating-point operation 
Float precision conversion 


UNDERFLOW 


UNDERFLOW (0) 
UNDERFLOW( 1 ) 
UNDERFLOW(Z) 


Any UNDERFLOW subcode 
Floating-point operation 
Float precision conversion 


ZERODIVIDE 

ZERODIVIDE(O) 
ZERODIVIDE ( 1 ) 
ZERODIVIDE(Z) 
ZERODIVIDEO) 


Any ZERODIVIDE subcode 
Decimal divide 
Floating-point divide 
Integer divide 


ENDFILE 


UNDEFINEDFILE 


KEY 


ENDPAGE 



In addition to these predefined system condition subcodes, you can define certain 
subcodes for a specific application, test for the desired condition, and then use the 
SIGNAL statement to signal the condition. 
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4.4.5 Condition Processing Built-in Functions 

PL/I provides certain built-in functions to help handle conditions when they occur. 
These functions are: 

■ ONCODE 

■ ONFILE 

■ ONKEY 

■ PAGENO 

■ LINENO 

The ONCODE function returns the subcode of the most recently signaled condition, 
or zero if no condition has been signaled. 

The ONFILE function returns the internal filename of the file involved in an I/O 
operation that signaled a condition. 

The ONKEY function returns the value of the last key involved in an I/O operation 
that signaled a condition. 

The PAGENO and LINENO functions return the current page number and line 
number for a PRINT file named as the parameter. 



4.5 Memory Management Statements 

Every variable in a PL/I program has a storage-class attribute. The storage class 
determines how and when PL/I allocates storage for a variable, and whether the variable 
has its own storage or shares storage with another variable. 

PL/I supports three different storage classes: 

■ STATIC 

■ AUTOMATIC (the default in PL/I) 

■ BASED 

PL/I treats AUTOMATIC storage as STATIC storage, except in procedures marked 
as RECURSIVE. The Compiler allocates storage for STATIC variables prior to exe- 
cution, and the storage remains allocated as long as the program is running. You can 
use the INITIAL attribute to assign initial constant values to STATIC data items. 
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Note: only STATIC variables can have the INITIAL attribute, to be compatible with 
the ANSI Subset G PL/I standard. 

Storage-class attributes are properties of scalars, arrays, major structure variables, 
and file variables. You cannot assign storage-class attributes to entry names, file con- 
stants, or members of data aggregates. 

4.5.1 BASED Variables and Pointers 

The Compiler does not allocate storage for variables with the BASED storage class. 
A based variable is a variable that describes storage that you must access with a pointer. 
The pointer is the location where the storage for the based variable begins, and the 
based variable itself determines how PL/I interprets the contents of the storage beginning 
at that location. Thus, the pointer and the based variable taken together are essentially 
equivalent to a nonbased variable. 

You can visualize a based variable as a template that overlays the storage specified 
by its base. Thus, a based variable can refer to storage allocated for the based variable 
itself, or to storage allocated for other variables. 

The format of the BASED variable declaration is, 

DECLARE name BASED[(pointer-reference)]; 

For example, 

declare A ( 5 » 5 ) character! 10) based? 
declare bit_vector bit(8) b a s e d ( p ) 5 

where the pointer reference is an unsubscripted POINTER variable, or a function call, 
with zero arguments, that returns a POINTER value. 

A pointer-qualified reference can be either implicit or explicit. When you declare a 
variable as BASED without a pointer reference, then each reference to the variable in 
the program must include an explicit pointer qualifier of the form, 

pointer-exp -> variable 
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When you declare a variable as BASED with a pointer reference, then you can 
reference it without a pointer qualifier. The run-time system reevaluates the pointer 
reference at each occurrence of the unqualified variable using the pointer expression 
given in the variable declaration. The following code sequence illustrates the concept 
of based variables. 

declare 

p pointer* 

a characterf 12B) » 

b(128) character(i) based (p)> 

c(0: 127) bit (8) based ( p) * 

d(G4) bit ( IB) based ( p) * 

e ( 8 1 : 1 5 ) b i t ( 8 ) based(p) i 



p = a d d r ( a ) 5 



In this example, after pointer p is set to the address of a, each of the variables b, c, 
d, and e refers to the same 128 bytes of storage occupied by the variable a, although 
they do so in different ways. Thus, the variables b, c, d, and e overlay the variable a. 



There is one important point to consider here. The overlays illustrated above depend 
on the method a particular processor uses to internally represent and store the data 
items. Such code makes a program implementation-dependent. For example, in imple- 
mentations other than PL/I, the internal representation of an array could include some 
header bytes in addition to the bytes used to represent the data elements. In each case, 
you must investigate the internal representation before using based variables to overlay 
other data types. 



43 



4.5 Memory Management Statements PL/I Programming Guide 

4.5.2 The ALLOCATE Statement 

The ALLOCATE statement explicitly allocates storage for a BASED variable. The 
ALLOCATE statement takes the form: 

ALLOCATE based variable SET(pointer variable); 

For example, 

allocate input_buf f e r se t < buf f e r_pt r ) 5 

The run-time system obtains sufficient memory for the based variable from the free 
storage area and then sets the pointer variable to the address of this memory segment. 

4.5.3 The FREE Statement 

The FREE statement releases the storage allocated to a BASED variable. The FREE 
statement takes the form: 

FREE [pointer variable ->] based variable; 

For example, 

free i n p u t_b u f f e r 5 

Note: the pointer variable reference is optional if you declared the based variable with 
a pointer reference. 
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The following code sequence illustrates the use of the ALLOCATE and FREE statements. 

declare 

(ptiir) pointer* 
a character based » 
b fixed based(r); 



allocate a set(p) 5 
allocate b sett r) i 
allocate a set(q) i 



free p - > a 5 
free <=i - > a 5 
free b 5 



4.6 Preprocessor Statements 

Preprocessor statements allow you to include other files and modify the source 
program at compile time. 

The % INCLUDE statement copies PL/I source from another file at compile time. 
The % INCLUDE statement is useful for filling in declarations that are repeated through- 
out a program. The % INCLUDE statement takes the form: 

%INCLUDE 'filespec'; 

For example, 

X include x f c b ♦ d c 1 ' 5 
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The % REPLACE statement allows you to replace identifiers by literal constants 
throughout the text of a PL/I program at compile time. The % REPLACE statement 
takes the form: 

% REPLACE identifier BY literal constant; 

You can put more than 1 identifier-constant pair in a single % REPLACE statement 
by separating the pairs with commas. 

For example, 

'/.replace 

true by M ' b » 
false by v ' b 5 



4.7 Null Statements 

The null statement does not perform any action. Its form is simply: 



You can use the null statement as the target of a THEN or ELSE clause in an IF 
statement. In the following example, 

if x > average then 

goto p rin t_i t 5 
else? 

no action takes place when x is less than or equal to average, and the sequence of 
execution continues at the statement following the ELSE. As another example, consider 
this statement: 

on en dpa^e ( repo rt_f i 1 e ) ; 

Here, no action takes place when PL/I processes the ON-unit for ENDPAGE, and the 
I/O statement that signaled the condition continues. 
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You can also use null statements to give more than one label to the same executable 
statement. For example, 

A:; 

B: statement- 1; 
statement-2; 



End of Section 4 



References: Section 4 LRM 
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PL/I is a free-format language. You can write programs without regard to column 
positions and specific line formats. Each line can be up to 120 characters long terminated 
by a carriage return, and logically connected to the next line in sequence. The Compiler 
simply reads the source program from the first through the last line, disregarding line 
boundaries. 

In exchange for this freedom of expression, you should adhere to some stylistic 
conventions, so that your programs can be easily read and understood by other pro- 
grammers. A professional program not only produces the correct output, but is con- 
sistent in form and divided into logical segments that are easy to comprehend. A 
logically structured program is also much easier to debug. A well-constructed program 
is appreciated for its form and its function. 

There are many stylistic conventions in use by individual programmers. The following 
rules illustrate one set of conventions that are used throughout the examples in this 
guide. Listing 5-1 illustrates the conventions presented in this section. 



5.1 Case 

You can write PL/I programs in either upper- or lower-case. Internally, the PL/I 
Compiler translates all characters, outside of string quotes, to upper-case. Using lower- 
case throughout programs generally improves readability. 



5.2 Indentation 

Use indentation throughout your program to set off various declarations and state- 
ments. To simplify indentation, the Compiler expands tabs ("I characters) to every 
fourth column position. Some text editors expand tabs to multiples of eight columns, 
so the line appears wider during the edit and display operations. The Compiler issues 
the TRUNC (truncate) error if the expanded line length exceeds 120 columns. 

Program statements start at the outer block level in the first column position. Each 
successive block level, initiated by a DO-group, BEGIN, or PROCEDURE block, starts 
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at a new indentation level, four spaces or one tab stop. Give statements in a group the 
same indentation level, with procedure names and labels on a single line by themselves. 

An IF statement should be directly followed by the condition and the THEN keyword, 
with the next statement indented on the next line. When the IF statement has an 
associated ELSE, start the ELSE at the same level as the IF. Indent the statement 
following the ELSE and place it on the next line. For declarations, place the DECLARE 
keyword on a single line, followed by the declared elements indented on the following 
line. 

Avoid complicated attribute factoring because it reduces program readability. Insert 
blank lines when necessary to improve paragraphing and to separate logically distinct 
segments of the program. 



5.3 Abbreviations 

Many of the longer PL/I keywords have abbreviations (see the PL/I Command Sum- 
mary for a complete list). Inconsistent use of abbreviations decreases readability, so 
use either the long or short forms, but not both. Make use of the underscore in variable 
names to improve readability. 



5.4 Modular Format 

You should divide large programs into several logical groups, or modules, where 
each module performs a specific primitive function. You should make these modules 
PL/I subroutines that are either locally or externally defined. Local subroutines become 
a part of the same main program or subprogram, while you can separately compile 
and link together external subroutines. 

Place locally defined subroutines at the end of the program, so that the beginning 
contains only declarations and top-level statements that call the local subroutines. 
Neither the top-level statements nor the locally defined subroutines should exceed one 
or two pages in length. 

While learning to program in PL/I, use a main program, with locally defined sub- 
routines, following the form of the examples in this guide. When your application 
programs increase in size, however, you will find it more effective to break them into 
separate modules. This allows you to compile and link individual segments in pieces, 
thereby reducing overall development time. 
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5.5 Comments 

Comments should become an integral part of your program. They are an essential 
element in making your program readable, for yourself and other programmers. Avoid 
introducing random comments throughout the source file, and do not nest them. Con- 
sistency is the watchword. Place your comments at the beginning of subroutines or 
logical statement groups. If your program is properly structured into well-defined 
modules, these explanatory remarks provide the information required to understand 
the overall purpose and operation of your program. They also simplify the task of 
maintaining and updating the code without introducing errors. 



/#*#*##**#*******####**#***#*###*###*♦#*****#*#/ 

/* This pros ram computes the largest of three */ 
/* FLOAT BINARY numbers m y> and z. */ 

/##*##*##*#*##**###*##*#*****##**####*****###**/ 
test : 

procedure options(main)! 

declare 

( a t b t c ) float binary! 

put 1 i 5 1 ('Type Three Numbers: ' ) ! 

Set list (aibtc)i 

put list ('The Largest Value is'»inax3(a>b»c))5 



/* this procedure computes the largest of x » y > and z #/ 
i — m a x 3 : procedure(x>y»z) returns(float binary)! 
declare 

( x » y » z » w a x ) float binary! 

i — if x > y then 

if x > z then 

max = x ! 
else 

max = z ! 
else 

if y > 2 then 

max = y ! 
else 

max = 2 ! 
return(max) ? 
e n d m a x 3 ! 



end test ! 



Listing 5-1. PL/I Stylistic Conventions 
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Using the System 



Developing a PL/I program is a 3-step process: 

1. Write the source file using ED or a similar text editor. 

2. Compile the source file and generate the relocatable object file. 

3. Link the relocatable object file with the Run-time Subroutine Library to gen- 
erate an executable command file. 

PL/I is a compiled language. Consequently, if you make any change to the source 
file, you must recompile the program. Try to divide large programs into several small 
modules, compile each module separately, then link them together. Small programs 
compile faster and use less storage for the Symbol Table. 

Figure 6-1 illustrates the development process. 




Figure 6-1. PL/I Program Development 
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6.1 PL/I System Files 

When you receive your PL/I system you should first copy all of the files onto a back- 
up disk. If you are unsure how to do this, read your operating system documentation. 

Note: you have certain responsibilities when making copies of Digital Research pro- 
grams. Be sure you read your licensing agreement. 

After you make back-up disks, load your Compiler disk and type a DIR command: 

A>'ii r 

The directory contains several types of files, as shown in Table 6-1. 

Table 6-1. PL/I System Files 



Type 


Definition 




CMD 


Executable command file (8086 implementation), for 
DEMO.CMD 


example, 


COM 


Executable command file (8080 implementation), for 
DEMO.COM 


example, 


DAT 


Default data filetype 




DCL 


% INCLUDE file (data declarations) 




IRL 


Indexed Relocatable File, for example PLILIB.IRL 




OBJ 


Relocatable object code file (8086 implementation), for 
DEMO.OBJ 


example, 


OVL 


PL/I Compiler Overlays (8080 implementation), PLIO, PLI1, 


and PLI2 


OVR 


PL/I Compiler Overlays (8086 implementation). PLIO, PLI1, 


and PLI2 
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Table 6-1. (continued) 



Type Definition 



PLI PL/I source programs, for example, DEMO.PLI 

PRN Printer disk file; compiled program listing on disk 

REL Relocatable object code file (8080 implementation), for example, 

DEMO.REL 

SYM Symbol Table File, for example DEMO.SYM 



Note: the only files that contain printable characters are the PLI source programs the 
PRN printer listing files and the SYM Symbol table files. 



6.2 Invoking the Compiler 

Invoke the PL/I Compiler using a command of the general form: 

pli filespec [$sl...$s7] 

where filespec designates the program to compile and can include an optional drive 
specification. For example, 

d:myfile.pli 

You need not specify the filetype because the Compiler assumes type PLI. 

$sl...$s7 represent a list of parameters that you can optionally include in the com- 
mand line when compiling a program. These parameters are called switches, and they 
enable the various Compiler options as shown in Table 6-2 on the following page. 

In each case, the single-letter option follows the $ symbol in the command line. You 
can specify a maximum of seven options following the dollar sign. The default mode 
using no options compiles the program but produces no source listing and sends all 
error messages to the console. 
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Table 6-2. PL/I Compiler Options 



Option Action Enabled 



B Built-in subroutine trace. Shows the Run-time Subroutine Library 

functions that are called by your PL/I program. 

D Disk file print. Sends the listing file to disk, using the filetype PRN. 

I Interlist source and machine code. Decodes the machine language 

code produced by the Compiler in a pseudo-assembly language form. 

K Kill parameter and % INCLUDE listings. Disables the listing of 

parameters and % INCLUDE statements during the Compiler's first 
pass. 

L List source program. Produces a listing of the source program with 

line numbers and machine code locations (automatically set by the 
I switch). 

N Nesting level display. Enables a pass 1 trace that shows exact balance 

of DO, PROCEDURE, and BEGIN statements with their corre- 
sponding END statements. 

O Object code off. Disables the output of relocatable object code nor- 

mally produced by the Compiler. 

P Page mode print. Inserts form-feeds every 60 lines, and sends the 

listing to the printer. 

S Symbol Table display. Shows the program variable names, along 

with their assigned, defaulted, and augmented attributes. 
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6.3 Compiler Operation 

The PL/I Compiler reads source program files and generates a relocatable, native 
code object file as output. PL/I is a 3-pass Compiler, with each pass a separate overlay. 
Pass 1 collects declarations, and builds a Symbol Table used by subsequent passes. 
Pass 2 processes executable statements, augments the Symbol Table, and generates 
intermediate language in tree-structure form. Both passes analyze the source text using 
recursive descent. 

Pass 3 performs the actual code generation, and includes a comprehensive code 
optimizer that processes the intermediate tree structures. Alternate forms of an equiv- 
alent expression are reduced to the same form, and expressions are rearranged to 
reduce the number of temporary variables. There is also a special-forms recognizer 
that detects and matches approximately three hundred tree structures of special interest. 
Special-forms recognition allows the Compiler to generate concise code sequences for 
many common statements. 

Note: all the Compiler overlays (PLIO, PLI1, and PLI2) must be on the default drive. 

As the Compiler proceeds through the first two passes, it displays the messages: 

NO ERROR(S) IN PASS 1 
NO ERROR(S) IN PASS 2 

If there are errors, the Compiler lists each line containing an error with the line number 
to the left, a short error message, and a ? below the position in the line where the error 
occurs. 

At the end Pass 3, the Compiler displays the message, 

CODE SIZE = m-mri 
DATA AREA = nnnn 
FREE SYMS = nnnn 
END COMPILATION 

where nnnn are hexadecimal numbers representing the amount of storage used for the 
code and data, as well as the amount of Transient Program Area (TPA) left for Symbol 
Table space. 
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Note: in the 8080 implementation, PL/I requires at least a 48K TPA. In the 8086 
implementation, PL/I requires an 96K TPA. 

If the number of error messages is excessive and you want to make corrections before 
proceeding, you can halt the compilation by typing a carriage return. The Compiler 
responds with the message: 

STOP PL/1 (Y/N>? 



Enter Y to halt the compilation. 

If you use the N switch, the Compiler lists the program line number on the left, 
followed by a letter a through z that denotes the nesting level for each line. The main 
program level is a, and each nested BEGIN advances the level by one letter, while each 
nested PROCEDURE advances the level by two letters. 

If you use the L switch, the Compiler lists the relative machine code address for each 
line as a four-digit hexadecimal number. This address is useful for determining the 
amount of machine code generated for each statement and the relative machine code 
address for each line of the program. The Compiler prints the source language statement 
on the line following the relative machine code value. 

Listings 6-la and 6-lb show two compilations of a program called DEMO that is 
on your sample program disk. 



1 a 

2 b 

3 b 
a b 
5 b 
G b 

7 b 

8 b 

9 b 

10 b 

11 b 

12 b 



demo 



procedure options(main)! 



declare 

name cha racte r(20) varyinSi 



put sKip(2) listPPLEASE ENTER YOUR FIRST NAME: ')» 

Set 1 i s t ( name ) i 

put skip(2) list( x HELL0 x ! ! name ! ! ' » WELCOME TO PL/I ') 



end demo? 



Listing 6-la. Compilation of DEMO Using $N Switch 
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1 a 0000 i— demo 

2 a 0006 

3 a 0006 

4 c 0006 

5 c 0006 

6 c 0006 

7 c 0006 
B c 0006 
9 c 0022 

10 c 003C 

11 c 006A 

12 a 006A l— end demo i 



procedure opt i oris (main ) ! 



declare 

name cha rac te r ( 20) yarvinsf! 



put skip(2) listTPLEASE ENTER YOUR FIRST NAME: ' 

Set 1 i st ( name ) ! 

put skip(2) listTHELLO '! Inamei! 'i WELCOME TO PL/I ') 



Listing 6-lb. Compilation of DEMO Using $L Switch 



6.4 The DEMO Program 

You can start learning to use the PL/I system by compiling the program called DEMO. 
The source file for DEMO is on your PL/I sample program disk, so you do not have 
to write the code. To display the source file, use the TYPE command, as follows: 

A > t y p e detrw * pi i 

To compile the DEMO program, enter the command: 

A > p I i demo 

Now examine your directory and find the object file that contains the relocatable 
machine code produced by the Compiler. The machine code produced by the Compiler 
is not directly executable, so you have to link the object file with the Run-time Sub- 
routine Library (RSL) with the command: 

A > link demo 

Now examine your directory and find the command file and the Symbol Table file 
produced by the linkage editor. You can load the Symbol Table file under SID™ or 
SID-86™ for debugging. 
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6.5 Running DEMO 

To run the compiled program, enter the name of the command file, 

A > d e m o 

The operating system loads the DEMO program, which begins processing and prompts 
you with the message, 

PLEASE ENTER YOUR FIRST NAME: 

Console input is free-field and incorporates the full line-editing facilities of the oper- 
ating system. When you enter your name, DEMO gives an appropriate response. Listing 
6-2 shows interaction with DEMO. 

A > d e m o 

PLEASE ENTER YOUR FIRST NAME: Larry 

HELLO Larry* WELCOME TO PL/I 
A> 

Listing 6-2. Interaction with the DEMO Program 

Various run-time errors can halt processing if the program does not explicitly inter- 
cept them. In this case, PL/I displays the message in the following form: 

error-condition (code), file-option, auxiliary-message 
Traceback: aaaa bbbb cccc dddd # eeee ffff gggg hhhh 

The error-condition is one of the standard PL/I condition categories (see Section 4.4.4). 
Code is an error subcode identifying the origin of the error. 

PL/I prints the file option when the error involves an I/O operation, and takes the 
form, 

File: internal = external 

where internal is the internal program name that references the file involved in the 
error, and external is the external device or filename associated with the file. PL/I prints 
the auxiliary message whenever the preceding information is insufficient to identify the 
error. 
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The traceback portion lists up to eight elements of the internal stack. In the preceding 
general form, element aaaa corresponds to the top of the stack, while hhhh corresponds 
to the bottom of the stack. If the stack depth exceeds eight elements, the # character 
separates the four topmost elements on the left from the four lowermost elements on 
the right. 

Listing 6-3 is an example of the diagnostic form. In this case, the console input is 
an end-of-file (CTRL-Z) character. Entering a CTRL-Z signals the ENDFILE condition 
for the SYSIN file. This is standard console input. In this example, the external device 
connected to the SYSIN file is the console, denoted by CON. 

A > d e m o 

PLEASE ENTER YOUR FIRST NAME: % Z 

END OF FILE (1)» File: SYSIN=CON 

Trace bacK: 07BE 0769 012E 4C00 » 0702 0322 8090 012E 

A> 

Listing 6-3. Error Traceback for the DEMO Program 



6.6 Error Messages and Codes 

PL/I prints error messages and codes during compilation and while running the 
compiled program. During compilation, nonfatal errors are marked with an error 
message following the line in error, with a ? character near the position of the line in 
error. The ? might follow the actual error position by a few columns. One error on a 
line in some cases leads to additional errors. 

Fatal errors, marked with an asterisk in the following list, cause the Compiler to 
halt immediately. Run-time errors occur while the program is running. Although some 
run-time errors are fatal, most can be intercepted using ON statements. The Compiler 
errors are listed first. 



61 



6.6 Error Messages and Codes PL/I Programming Guide 

6.6.1 General Errors 

DIR FULL* The operating system's disk directory has overflowed. Erase unnec- 
essary files and try again. 

DISK FULL* All disk file space has been consumed. Erase unnecessary files and 
try again. 

'INVALID INCLUDE A %INCLUDE statement is not properly formed. The 
% INCLUDE statement has the general form 

% include 'drfilename.typ'; 

where d is the (optional) drive, and filename.typ is the file specification. 

LENGTH The item exceeds the maximum field width for the keyword or data item 
(31 characters for identifiers, 128 for strings). 

NO FILE x* The file x does not exist on disk. If x is of type PLI, then check to 
see that your source file is on the named disk. If the type is OVR, or OVL, then ensure 
that all three PL/I Compiler overlays (PLIO, PLI1, PLI2) are on the default disk. 

OUT OF MEMORY The memory size of the host system is too small. In the 8080 
implementation, PL/I requires at least a 48 K Transient Program Area (TPA) for program 
compilation. In the 8086 implementation, PL/I requires a 96K TPA. 

READ ONLY x* The named file cannot be closed. Typically caused by disk that 
is set to Read-Only through hardware. 

TERMINATED** Program error count exceeds 255, or terminated at the console 
by user typing return during the compilation process. 

TRUNC Line exceeds 120 characters in length and has been truncated. 

UNEXPECTED EOF* The end of the source program was encountered before the 
logical end of program. Typically due to unbalanced block levels (recompile with the 
$n toggle for nesting trace), or unbalanced comments and strings (check balance for 
missing */ or apostrophe characters). 

VALUE Indicates that the converted number exceeds the 16-bit capacity for FIXED 
BINARY constants (-32768, +32767). 
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6.6.2 Pass 1 Errors 

BAD UAL The constant encountered in a format is invalid for this format item. 

BALANCE The parentheses for the expression are not balanced. 

BLOCK AT LINE x VARIABLE u EXCEEDS STORAGE The block begin- 
ning at source line x contains a variable v that caused the collective allocation of storage 
to exceed 65535 bytes. 

BLOCKOVERFLOW The nesting level of PROCEDURE, DO, and BEGIN blocks 
exceeds thirty-one levels. Simplify the program structure and try again. 

CONFLICT The attributes given in a declaration conflict with one another. 

D U P L I C The indicated variable is declared more than once within this block. 

LABEL The label for this statement is not properly formed. Only one label per 
statement is allowed, and subscripted label constants must have constant indexes. 

LENGTH The length of the indicated symbol exceeds the maximum symbol size. 
Simplify the structure and retry. Can also be caused by an unbalanced string. 

NESTED REP The % REPLACE statement is placed improperly in the block struc- 
ture. % REPLACE statements must occur at the outer block level before the occurrence 
of nested inner blocks. 

NO D C L : u 1 t u 2 > ♦ ♦ ♦ tun The listed procedure parameters occurred in 
the procedure header, but were not declared within the procedure body. 

NOT BIF The BUILTIN attribute is applied to an identifier that is not a PL/I 
built-in function. 

NOT IMP The statement uses a feature that is not implemented in PL/I. 

NOT VARIABLE The declared name is treated as a variable, but does not have 
the VARIABLE attribute. 

NUMBER Numeric constant is required at this position in the format. 
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ON BODY Invalid statement occurs in the ON condition body. RETURN cannot 
be used to exit from an ON-unit. DO and IF require enclosing BEGIN... END block. 

PICTURE Picture declaration or P format item is improperly formed. 

RECUR PROC Recursive procedure contains invalid nested block. Only embedded 
DO-groups are allowed in recursive procedures. 

STRUCTURE The indicated structure is improperly formed. Nesting levels cannot 
exceed 255. 

SYMBOL LENGTH OVERFLOW* Maximum symbol size exceeded during con- 
struction of Symbol Table entry. Simplify and try again. 

SYMBOL TABLE OVERFLOW* This program cannot be compiled in the current 
memory size. Break the module into separate compilations, or increase the size of the 
TPA on your system. 

SYNTAX The specified statement is improperly formed. See the PL/I Language 
Reference Manual for proper statement formulation. 

6.6.3 Pass 2 Errors 

AGG UAL Actual parameter is an aggregate value that does not match the formal 
parameter. Change actual or formal parameter to match. 

ARG COUNT One of the following has occurred: subscript count does not match 
declaration; DEFINED reference to array element; more than 15 bound pairs; bound 
pairs do not match; or formal and actual parameter count does not match. 

BASE Invalid based variable reference. Occurs when pointer qualifier references 
nonbased variable, or variable is declared BASED(x), where x is not a simple pointer 
variable or simple pointer function call, as in BASED(P) or BASED(Q()). 

BASED REO A based variable is required in this context. 

BAD TYPE Control variable in iterative DO-group is invalid. Only scalar variables 
are allowed. 

BAD VALUE Invalid argument to built-in function. 
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BALANCE The parentheses for this expression are unbalanced. 

B I T C N Bit substring constant is out of range. The last argument to bit SUBSTR 
must be a constant in the range 1 to 16. 

BIT REO A bit expression is required in this context. 

CLOSURE The label following the END does not match the preceding correspond- 
ing PROCEDURE name. 

COMPREO A noncomputational expression has been used where a computational 
expression is required. 

COMPILER ERROR A compiler error has occurred. The error might be due to 
previous errors. 

CONFLICT Data attributes are in conflict, or attributes in OPEN statement are 
not compatible. 

CONVERT Cannot convert the constant to the required type. 

EXPRESSION OVERFLOW* The expression has overflowed the Compiler's internal 
structures. Simplify and try again. 

ID REO An identifier is required in this context. 

INT REO An integer (FIXED BINARY) expression is required in this context. 

LABEL Improperly formed label encountered where label expected. 

NO BUILTIN Referenced built-in function not implemented in PL/I. 

NO DCL Indicated variable has not been declared in the scope of this reference. 

NOT FILE The reference within a FILE option is not a file variable or file constant. 

NOT FORMAT The format field of a GET or PUT EDIT does not reference a 
format. 

NOT IMP The construct in this statement is not implemented in PL/I. 



65 



6.6 Error Messages and Codes PL/I Programming Guide 

NOT KEY The expression within a KEYTO, KEYFROM, or KEY option is not a 
FIXED BINARY variable. 

NOT LABEL The target of this GOTO statement is not a label value. 

NOT P R C The reference following a CALL is not a procedure value. 

NOT SCALAR A nonscalar value was encountered in a context requiring a scalar 
expression. 

NOT STATIC An attempt was made to initialize automatic storage. Declare with 
STATIC attribute and retry. 

P T R R E A pointer variable is required in this context. 

QUALIFY This reference to a structure does not properly qualify the variable 
name; usually due to nonunique substructure reference. 

RET EXP The expression in a return statement is not compatible with the RETURNS 
attribute of the corresponding procedure. 

RETURN An attempt to return value from procedure was made without RETURNS 
attribute. 

SYNTAX Statement is improperly formed. See PL/I Language Reference Manual 
for proper statement formulation. 

SCALE GREATER THAN The resulting FIXED BINARY expression produces 
a nonzero scale factor. If the expression involved division, replace x/y by DIVIDE(x,y,0). 
This is necessary to maintain full language compatibility. 

SYMBOL TABLE OVERFLOW* Free memory space exhausted during compila- 
tion. (See similar error in Pass 1.) 

S T R R E Q A string variable is required in this context. In the case of the SUBSTR 
built-in function, assign the expression to a temporary variable before the substring 
operation takes place. 

TYPES NOT= The types of a binary operation are not compatible. Check dec- 
larations and conversion rules. Might be due to aggregate data items that do not match 
in structure. 
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UNSPEC Source or target of UNSPEC operation is not an 8- or 16-bit variable. 

# VALUES The number of items specified in an INITIAL statement is not com- 
patible with the variable being initialized. 

V A R R E A variable is required in this context. 

6.6.4 Pass 3 Errors 

***AUTOMATIC STORAGE OVERFLOW*** The total storage defined within 
this program module exceeds 65535 bytes. 

BAD INT FILE The intermediate file sent to Pass 3 is invalid, and is usually due 
to a hardware malfunction. 

BLOCK OVERFLOW Nesting level has exceeded the Compiler's internal tables 
(maximum 32 levels). 

EOF ON INT FILE Premature end-of-file encountered while reading interme- 
diate file. Usually due to hardware failure. 

EXPRESSION OVERFLOW* The Compiler's internal structure sizes have been 
exceeded. Simplify expression and retry. 

LINE x OPERATION NOT IMPLEMENTED An invalid intermediate opera- 
tion has occurred. Usually due to hardware failure or errors in a previous pass. 

6.6.5 Run-time Errors 

Run-time errors occur when the linked program is loaded and executed. Run-time 
errors are divided into two categories: fatal errors, which stop execution, and nonfatal 
errors, which can be intercepted with ON-units. 

6.6.6 Fatal Run-time Errors 

FREE REQUEST OUT OF RANGE A FREE statement specifies a storage address 
outside the range of the free storage area, and is usually caused by reference to an 
uninitialized base pointer. 
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FREE SPACE OVERWRITE The free storage area has been destroyed, and is 
usually caused by an out-of-range subscript reference or a stack overflow. If stack 
overflow occurs, use the STACK(n) keyword in the OPTIONS field to increase the 
stack size. 

INSUFFICIENT MEMORY The loaded program cannot execute in the memory 
size allocated to the transient program. If possible, increase the size of the Transient 
Program Area. 

INVALID I/O LIST The list of active files has been destroyed during execu- 
tion, and the attempt to close all active files at the end of execution failed. Usually due 
to subscript values out-of-range. 

6.6.7 Nonfatal Errors 

The following errors are printed when no ON-unit is active, or if control returns 
from an ON-unit corresponding to a fatal condition (marked by an asterisk). In each 
case, the condition prefix is listed, followed by an optional subcode that identifies the 
error source, followed in some cases by an auxiliary message that further identifies the 
source of the error. 

ERROR ( 1 ) "Conversion"* Occurs whenever conversion cannot be per- 
formed between data types, and might be signaled during arithmetic operations, assign- 
ments, and I/O processing with GET and PUT statements. 

ERROR ( 2 ) "I/O Stack Overflow"* The run-time I/O stack has exceeded 
16 simultaneous nested I/O operations. Simplify the source program and try again. 

ERROR ( 3 ) * Transcendental function argument is out-of-range. 

ERROR ( a ) "I/O Conflict x"# A file has been explicitly or implicitly opened 
with one set of attributes, and subsequently accessed with a statement requiring con- 
flicting attributes. The value of x is one of the following: 

■ STREAM/RECORD 

■ SEQUEN/DIRECT 

■ INPUT/OUTPUT 

■ KEYED Access 

The first conflict arises when ASCII files are processed using READ or WRITE, but 
the INTO or FROM option does not specify a varying character string. 
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E R R R ( 5 ) "Format Overflow"* The nesting level of embedded formats 
has exceeded 32. Simplify the program and try again. 

E R R R ( S ) "Invalid Format Item"* The format processor has encoun- 
tered a format item that cannot be processed. The P format is not implemented in 
PL/I. 

ERR0R(7) "Free Space Exhausted"* No more free space is available. 
If intercepted by an ON-unit, do not execute ALLOCATE, OPEN, or recursion without 
first releasing storage. 

ERR0R(8) "OVERLAY* NO FILE d:f ilenawe" The indicated file could 
not be found. 

ERROR ( 9 ) " OVERLAY » DR I VE d : f i 1 en awe " An invalid drive code was 
passed as a parameter to overlay. 

ERROR ( 1 ) "OVERLAY * SIZE d : f i 1 e n aw e " The indicated overlay will 
overwrite the PL/I stack and/or free space if loaded. 

ERROR(ll) "OVERLAY* NESTING d:f ilenawe" Loading the indi- 
cated overlay would exceed the maximum nesting depth. 

ERROR (12) "OVERLAY* READ dsf ilenawe" Disk read error during 
overlay load; probably caused by premature EOF. 

ERROR ( 1 3 ) "Invalid OS Version" Caused by any operation that gen- 
erates an operating system call not supported under the current operating system. 

ERROR ( 1 4 ) "Unsuccessful Write" Caused by any unsuccessful write 
operation on a file due to lack of directory space, lack of disk space, etc. 

ERR0R(15) "File Not Open" Caused by any attempt to lock or unlock a 
record in a file that is not open. 

ERROR(IS) "File Not Keyed" Caused by any attempt to lock or unlock 
a record in a file that does not have the KEYED attribute. 

FIXED OVERFLOW A decimal add or multiply produced a value exceeding 15 
decimal digits of precision, or an attempt was made to store to a variable with insuf- 
ficient precision. 
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OVERFLOW* 1) A floating-point operation produced a value too large to be rep- 
resented in floating-point format. 

0MERFL0W<2) A double-precision floating-point value has been assigned to a 
single-precision value with insufficient precision. 

UNDERFLOW(l) A floating-point operation produced a value too small to be 
represented in floating-point format. 

UNDERFL0W(2) A double-precision floating-point value has been assigned to a 
single-precision value with insufficient precision. 

ZERODIUIDE(l) A decimal divide or modulus operation was attempted with a 
divisor of zero. 

ZER0DIUIDE(2) A floating-point divide or modulus operation was attempted 
with a divisor of zero. 

ZERQDIUIDEO) An integer divide or modulus operation was attempted with 
a divisor of zero. 

ENDFILE An attempt was made to read past the end of the listed file, or the disk 
full condition occurred during output. 

UNDEFINEDFILE The named file cannot be found on the disk if input, or cannot 
be created if output. Also occurs when an input device is opened for output, or an 
output device is opened for input. 

K E Y ( 1 ) Invalid key detected in output operation. 

K E Y ( 2 ) Invalid key encountered during input operation. 

ENDPAGE An end-of-page condition was detected. This condition does not cause 
termination if no ON-unit is active. 

End of Section 6 
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PL/I programs allow you to use different data types to suit different applications. In 
programs throughout the manual, you should note how and why each type of data is 
used in a particular situation. 



7.1 The FLTPOLY Program 

Listing 7-1 shows a program for evaluating a polynomial expression. The program 
begins by reading three values, x, y, and z, from the console, and then uses the values 
to evaluate the polynomial expression: 

p ( x t y t z ) = x ^ + 2 y + z 

The main part of the program is bounded by a single DO-group. On each successive 
iteration, the program reads the values of x, y, and z from the standard SYSIN, console, 
file. The program then writes the value produced by p(x,y,z) to the SYSPRINT file, 
again, the console file. Finally, if all the input values are zero, the program executes 
the STOP statement and ends the indefinite loop. 

The program uses the % REPLACE statement on line 8 to define the literal value of 
true as the bit-string constant, 'l'b. The Compiler substitutes this value whenever it 
encounters the name true. Thus, the Compiler interprets the DO-group beginning on 
line 13 as, 

do w h i 1 e ( M ' b ) 5 



e n d ? 

which loops until it executes the contained STOP statement. Using % REPLACE state- 
ments to define constants can improve the readability of your programs. 
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1 a 



/******************#*****#♦**#**#♦*******####*#*###/ 
/* This program evaluates a polynomial expression */ 



3 a 


/* 


usinsf FLOAT BINARY data. */ 


4 a 


/***********##*****#*##****##******##*****#**#*####/ 


5 a 


- fit 


poly : 




G b 




procedure opt ions ( main ) ! 


7 b 








8 b 




^replace 




9 b 




true b) 


M ' b ; 


10 b 




declare 




11 b 




( x t y i z ) 


float binary (24) i 


12 b 








13 c 






do while(true)? 


14 c 






put s K i p 


2) 1 i s t ( ' T y p e mnz: ' ) ! 


15 c 






Set list 


x >v >z ) i 


IB c 










17 c 






if x=0 & 


y=0 & z = then 


18 c 






stop ! 




19 c 










20 c 






put s K i p 


listr 2') i 


21 c 






put sK i p 


list (' x +2y+z='tP(xty»z)); 


22 c 






end ! 




23 b 








24 b 






P: 




25 c 






procedure 


(x»y»z) returns (float binary(24))5 


26 c 






declare 




27 c 






(x iy 


» z ) float binary! 


28 c 






return ( x 


* x + 2 * y + z) 5 


29 c 






end P! 




30 b 








31 b 


- et 


id 


f ltpoly ; 





Listing 7-1. Polynomial Evaluation Program (FLOAT BINARY) 
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Listing 7-2 shows the console interaction with the FLTPOLY program. The initial 
values for x, y, and z are: 1.4, 2.3, and 5.67, but on the next loop, the input takes the 
form: 

»4.5 * t 

This form changes the value of y only. Thus, on this loop, the values of x, y, and z 
are 1.4, 4.5, and 5.67. The third input line changes y and z, while the fourth line 
changes x only. 

(\>fltP0ly 

Type xtrtz: 1,4, 2,3, 5,67 

x + 2v + z = 1 .223000E+01 
Type x >>■ >z : > 4 .5 > > 

x + 2y + z = 1 .GG3000E+01 
Type x >y tz : t , Be -3 , 7 

x + 2v + z = 0.89G119E+01 
Type x >y >z : 2 ,3 > > > 

x + 2v + z = 1.229119E+01 
Type x >y >x : >0 >0 
A> 

Listing 7-2. Interaction with FLTPOLY Program 
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7.2 The DECPOLY Program 

Listing 7-3 shows the DECPOLY program, which is essentially the same program 
as Listing 7-1. The difference between the two programs is that FLTPOLY uses FLOAT 
BINARY data items, while DECPOLY uses FIXED DECIMAL items. FLOAT BINARY 
computations execute significantly faster than their FIXED DECIMAL equivalents, but 
single-precision FLOAT BINARY computations involve truncation errors, and produce 
an answer with only about 7 decimal places of accuracy. 



1 


a 


/***#**##*#*********#***#*♦****#********#**#♦****#*/ 


2 


a 


/* This p ro i ram 


evaluates a polynomial expression */ 


3 


a 


/* usin* FIXED DECIMAL data, */ 


a 


a 


/♦ft*******************************************-*****/ 


5 


a 


r~ d 


?cpo1 y : 




B 


b 




procedure opt i ons (main ) i 


7 


b 








8 


b 




I r e p 1 a c e 




9 


b 




true bv 


M 'b i 


10 


b 




declare 




11 


b 




(mviz) 


fixed decimal ( 15 »4) i 


12 


b 








13 


c 




— do wh i 1 e ( t rue ) i 


14 


c 




put s K i p ( 


2) 1 i st ( 'Type x >y »z : ' ) 5 


15 


c 




set 1 ist ( 


x t y t z ) i 


IB 


c 








17 


c 




if x = & 


y=0 & z=0 then 


IB 


c 




StOP I 




19 


c 








20 


c 




put skip 


1 ist ( * 2') i 


21 


c 




put sK ip 


list! ' x +2y + z='»P(x»y»z))5 


22 


c 




' — end ! 




23 


b 








24 


b 




|— P: 




25 


c 




procedure 


(x»y»z) returns (fixed deciinal(15i4))i 


2B 


c 




declare 




27 


c 




( X t> 


>z) fixed deciiital(15»4)i 


28 


c 




return ( x 


*x+2*y+z)i 


29 


c 




- end Pi 




30 


b 








31 


b 


— ei 


id decpoly! 





Listing 7-3. Polynomial Evaluation Program (FIXED DECIMAL) 
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Listing 7-4 shows the console interaction with the DECPOLY program. The initial 
input values for x, y, and z are: 1.4, 2.3, and 5.67. These are the same values used for 
the FLTPOLY program, but notice the difference in the output. The second loop changes 
the values of y and z, and the third loop changes all three values. 

A>decpoi>' 

Type x ,y »z: 1 , 4 , 2,3 , 5,67 

2 
x + 2/ + z = 12.2300 

Type myiz: > ,0006 > 7 

2 
x + 2y + z = 8.9G12 

Type xi/iz: 723, HQ5 , 80,54, 

2 
x + 2y + z = 523533.7480 

Type x t y i z : i0 i > 

A> 

Listing 7-4. Interaction with DECPOLY Program 

Experiment with these two programs by comparing the results when you enter the 
same values in each one. Then read Section 17, which describes the internal data 
representation for all PL/I data types. Understanding how PL/I internally treats the 
different data types helps you choose the right type of data to suit the application. 

End of Section 7 
References: Section 3.1 LRM 
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Section 8 

STREAM and RECORD File 

Processing 



The example programs in this section illustrate STREAM and RECORD file process- 
ing using the various I/O statements. 



8.1 File Copy Program 

Listing 8-1 shows a general purpose, file-to-file copy program. The program first 
defines and opens two file constants called input_file and output_file. It then begins 
executing a continuous loop that reads data from inputfile and copies it to output_file. 

Both OPEN statements define STREAM files with internal buffers of 8192 characters 
each. In the first OPEN statement, PL/I supplies the default attribute INPUT, while the 
second OPEN statement explicitly specifies an OUTPUT file. Otherwise, it would also 
default to an INPUT file. 

This program shows the special use of READ and WRITE statements to process 
STREAM files. The READ statement on line 19 reads a STREAM file into buff, a 
character string of varying length. It reads each line of input up to and including the 
next carriage return line-feed into buff, and sets the length of buff to the amount of 
data read, including the carriage return line-feed character. The WRITE statement 
performs the opposite action. It sends the data to a STREAM file from buff. The output 
file receives all characters from the first position through the length of buff. 

The program terminates by reading through the input file until it reaches the end- 
of-file (CTRL-Z) character. PL/I automatically closes all open files, and writes the 
internal buffers onto the disk, thus preserving the newly created output file. 
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1 a /**#*#******##*#**##*#**************#***♦#**#***##/ 

2 a /* This program copies one file to another usins' */ 
3a /* buffered I/O, #/ 

4 a /*#******#*###**#*****#***********#*#♦#**#*******#/ 

5 a i — copy : 



6 b 

7 b 

8 b 

9 b 

10 b 

11 b 

12 b 

13 b 

14 b 

15 b 

16 b 

17 b 

18 c 

19 c 

20 c 

21 c 

22 b 



procedure opt i ons (main ) 5 
declare 

( input_f i le »outPut_f i le ) file! 

open file (input_file) stream 

environment(b(B192)) title(*$l»$l'); 

open file ( outPut_f i 1 e ) stream output 

enyironment(b(8192)) titled $2, *2')5 
declare 

buff characte r (254) uar/inSi 

do whi le ( ' 1 'b ) 5 

read file (input_file) into (buff)? 
write file ( outPut_f i 1 e ) from (buff)? 
end ! 
end c o p v i 



Listing 8-1. COPY (File-to-File) Program 

Listing 8-2 shows a sample execution of the copy program using the following 
command line: 

A > c o p y copy * pi i $con 

In this case, the input file is COPY.PLI, the original source file, while the output file 
is the system console. Thus, the program simply lists COPY.PLI at the terminal. 

The TITLE options connect the internal filenames to external devices and files. The 
command line has two parts: the command itself, and the command tail, which can 
contain two filenames. 



Command 




Command Tail 
1^^ $2 




copy 


copy.pli 


$con 



Figure 8-1. Default Filenames in the Command Tail 
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The OPEN statement on line 10 takes the first default name, including the drive in 
the command tail (denoted by $1.$1), and assigns it to the internal file constant called 
input_file. Similarly, the second OPEN statement on line 13 takes the second default 
name including the drive in the command tail (denoted by $2. $2), and assigns it to 
the internal file constant called output_file. 

For example, the command, 

A > c o f y a : x * d a t c : u * new 

copies the file X.DAT from drive a to the new file U.NEW on drive c. The input file 
must exist, but PL/I erases the output file if it exists, and recreates it. 

A>cdp>' coPYtPli $con 

1 a /#**#******#*##♦*#*##*******##**#*****###***#**##*/ 

2 a /* This program copies one file to another us ins! */ 
3a /* buffered I/O, */ 

4 a /a**********************************************-**/ 

5 a copy : 

G b procedure opt i ons (main ) ? 

7b declare 

8 b ( input_f ile »outPut_f i le) file? 

9 b 

10 b open file (input_file) stream 

11 b enui ronment (b (8192) ) t i t 1 e ( ' $1 , $1 ' ) i 

12 b 

13 b open file ( outPUt_f i 1 e ) stream output 

14 b envi ronment (b(8192) ) t itle ( v *2.$2 ' ) 5 
15b declare 

IB b buff character(254) uaryinsfi 

17 b 

18 c do whilet M 'b) ! 

19 c read file (input_file) into (buff)! 

20 c write file ( outPut_f i 1 e ) froM (buff)i 
21c end i 

22 b end copy i 

END OF FILE (3)t File: INPUT=C0PY . PLI 

Traceback : 044B 03AF 0155 

A> 

Listing 8-2. Interaction with the COPY Program 
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8.2 Name and Address File 

The two programs in Listings 8-3 and 8-6 manage a simple name and address file. 
The CREATE program produces a STREAM file containing individual names and 
addresses that are subsequently accessed by the RETRIEVE program. 

8.2.1 The CREATE Program 

The CREATE program in Listing 8-3 contains a data structure that defines the name, 
address, city, state, zip code, and phone number format. This data structure is not in 
the source file CREATE.PLI. It is contained in a separate file named RECORD.DCL, 
and CREATE uses an % INCLUDE statement to read and merge this file with the source 
file. Both files are on your sample program disk. The + symbols to the right of the 
source line number in the listing indicate that the code comes from an % INCLUDE 
file. The actual line in the source program appears as follows: 

c reate s 

procedure optionsdiiain) 5 

"/» i n c 1 u d e x r e c o r d ♦ d c 1 ' 5 

The file specified in the %INCLUDE statement can be any valid filename. The Compiler 
simply copies the file at the point of the %INCLUDE statement, and then continues. 

The OPEN statement, line 29, does not specify the PRINT attribute. This means the 
output file is in a form suitable for later input using a GET LIST statement. 

1 a /*##*#**#**#***#*###*##******##*##*•**##**###****#*#*##/ 

2 a /* This program creates a natae and address file. The */ 
3a /* data structure for each record is in the ^INCLUDE */ 
4a /* file RECORD.DCL. */ 
5 a /**####**#***##*###***#**##***##****##*#***#****###**#/ 

r— c reate : 

procedure opt i ons ( main ) 5 



6 a 

7 b 

8 b 



Listing 8-3. CREATE Program 
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9 + b 

10 + b 

11 + b 
12+b 
13 + b 

i<a+b 

15 + b 

IB + b 

17 b 

18 

19 

20 

21 



23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
3G 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 

48 d 

49 d 
50 
51 
52 
53 
54 



declare 

1 record* 

2 name 

2 addr 

2 city 

2 state 

2 zip 



c h a r a c t e r ( 30 ) u a r y i in S > 
c h a r a c t e r ( 3 ) v a r y i n S » 
c h a r a c t e r ( 2 ) v a r y i n 3 * 
character(lO) v a r y i n S * 
fixed decimal (G)t 



1 replace 
true by 



2 phone character<12) u a r y i n 3 i 



1 



false by * ' b 5 

declare 

output file* 

filename character(14) u a r y i n 3 * 

eofile bit(l) static i n i t i a 1 ( false)! 

put list ('NaMe and Address Creation Pro 3 ram* File Name: ')S 
Set list (fil ename ) 1 

open file(output) stream output t i 1 1 e ( f i 1 ename ) 5 

i — do while ('' eofile)? 

put skip(3) list ('Name; ')» 

Set 1 i s t ( n a m e ) 5 

eofile = ( name = l EOF ' ) 5 

if "eofile then 

— do i 



/ # write prompt strings to console # / 

put list( v Ad dress: ' ) ! 

Set 1 i st ( add r ) 3 

put li st( v City» State* Zip; ' ) 5 

Set 1 i s t ( c i t y > state* zip)! 

put list( v Phone; ' ) 5 

Set list(phone)! 

/ ft data in Memory* write to output file # / 
put f i 1 e ( o u t p u t ) 

list(name*addr*city*state*zip>phone)5 
put file(output) s K i p 5 

end 1 

end i 

put file (output) skip list('EOF'); 

put file(output) skip! 



— end create? 



Listing 8-3. (continued) 



81 



8.2 Name and Address File PL/I Programming Guide 

Listing 8-4 shows the console interaction with the CREATE program. You specify the 
output file as names.dat in the first input line. The GET LIST statement, line 33, accepts 
input delimited by blanks and commas, unless the delimiters are included in single 
apostrophes. Thus, CREATE takes the input line, 

'John Robinson 

as a single string value with PL/I automatically inserting the implied closing apostrophe 
at the end of the line. The last entry includes the three input values, 

Unknown* v Can''t Find'* 99999 

that CREATE assigns to the variables city, street, and state. Because the first value 
does not begin with an apostrophe, the I/O system scans the data item until the next 
blank, tab, comma, or end-of-line occurs. The second data item begins with an apos- 
trophe, and this causes the I/O system to consume all input through the trailing balanced 
apostrophe, and reduce all embedded double apostrophes to a single apostrophe. The 
last value, 99999, is assigned to a decimal number, and must contain only numeric 
data. 

You can use the command, 

A > t y p & names * dat 

to display the STREAM file that the program creates. Listing 8-5 shows the output 
resulting from each input entry. 

A>c reate 

Name and Address Creation ProSranit File Name: names.dat 



Nante: 'Arthur Jackson' 

Address: '100 14, 3rd St, ' 

City» State* Zip: 'Fresno'* 'Ca,'t 93706 

Phone: '529-1277' 



Name : 'Donna Harris ' 

Address: '2999 Serra Rd,' 

Cit/i State* Zip: 'Chico't 'Ca,'» 95926 

Phone: '635-3570' 

Listing 8-4. Interaction with the CREATE Program 
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Name: 'John Robinson 
Address: '805 FranKlin St,' 
City » State* Zip: 'Monterey 
Phone: '643-1000' 



'Ca. ' > 93940 



Nairie: 'Virginia Hilson' 

Address: ' ? ' 

City* State* Zip: UnKnown> 'Can''t Find't 33399 

Phone: '?' 



Name 



'EOF' 



Listing 8-4. (continued) 

A>type names , dat 

'Arthur JacKson' MOO W. 3rd St,' 'Fresno' 'Ca.' 9370G K 529- 1277 ' 
'Donna Harris' '2999 Serra Rd,' 'Chico' 'Ca.' 95926 '635-3570' 
'John Robinson' '805 FranKlin St,' 'Monterey' 'Ca,' 93940 '649-1000' 
'Virginia Wilson' '?' 'Unknown' 'Can''t Find' 99999 '?' 

'EOF' 
A> 

Listing 8-5. Output from the CREATE Program 

8.2.2 The RETRIEVE Program 

The RETRIEVE program shown in Listing 8-6 reads the file created by CREATE, 
and displays the name and address data upon user request. The Compiler includes the 
same RECORD.DCL file used in the CREATE program, shown in Listing 8-3. 

The main DO-group in the RETRIEVE program, between lines 30 and 59, reads 
two string values corresponding to the lowest and highest names to print on each 
iteration. The embedded DO-group between lines 41 and 57 reads the entire input file 
and lists only those names between the lower and upper bounds. 

The RETRIEVE program, similar to the CREATE program, reads the name of the 
source file from the console. However, RETRIEVE opens and closes this source file 
each time it receives a retrieval request from the console. 
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The OPEN statement on line 38 sets the internal buffer size of the input file to 1024 
bytes. After processing the file, RETRIEVE executes the CLOSE statement on line 58 
and flushes all internal buffers. Thus, RETRIEVE sets the input file back to the beginning 
on each retrieval request. 



1 a 

2 a 

3 a 
a a 

5 a 

6 b 

7 b 
8+b 
9+b 

10+b 
11 + b 
12+b 
13+b 
14+b 
15+b 
16 b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
c 
c 
c 
c 
c 
c 
c 



17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 



/* This program reads a name and address data file */ 
/* and displays the information on request. */ 

ret rie v e : 

procedure options (wain ) 5 



declare 

1 reco rd » 
2 name 
2 addr 
2 city 



^replace 
t rue 



cha racte r(30) varying'* 

character(30) varying* 

cha racte r( 20) varying* 

2 state characte r( 10) varying* 

2 zip fixed decimal (6) * 

2 phone cha racte r( 12) varying! 

by M 'b » 



false by 'O'b 5 

declare 

(sysprint > input ) file* 
filename characte r( 14 ) varying* 
(lower* upper) characte r (30) varying* 
eof ile bit ( 1 ) 5 

open fi le ( sysprint ) print t i t le ( '$con ' ) ! 

put listt'Name and Address Retrieval* File Name: 

get 1 ist ( f i lename ) ! 



') i 



do whi le ( t rue ) 5 

lower = ^AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA'5 
upper = v zzzzzzzzzzzzzzzzzzzzzzzzzzzzzz ' 5 
put skip(2) lisU'Type Lower* Upper Bounds: ')5 
get 1 ist ( 1 owe r tuppe r) i 
if lower = x E0F' then 
stop? 



Listing 8-6. RETRIEVE Program 
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38 c 






oper 


fil 


e(input) stream input en v i ranmen t ( b ( 1024 ) 


39 c 




t i t le ( f i lename ) ! 


40 c 




eofile = false! 


41 d 






— do while ("eofile)! 


42 d 






Set file( input) 1 ist (name ) 5 


43 d 






eofile = (name = 'EOF ' ) i 


44 d 






if"eofilethen 


45 e 








— do 5 


4G e 








Set f i le ( input ) 


47 e 








list(addr>cityistatetzip»phone)i 


48 e 








if name >= lower & name <= upper then 


49 f 










— do ; 


50 f 










put paSe sKip (3) 1 ist (name ) ! 


51 f 










put sKip 1 ist ( add r ) i 


52 f 










put sKip 1 ist ( city tstate ) ! 


53 f 










put skip 1 ist (zip) ! 


54 f 










put sKip 1 ist ( phone ) ! 


55 f 










— end! 


56 e 








' — end i 


57 d 






' — end ! 


58 c 




close file(input)! 


59 c 




— end i 


GO b 




61 b 


— er 


id r 


et ri ei 


e i 





Listing 8-6. (continued) 

Listing 8-7 shows user interaction with the RETRIEVE program. Again, the input 
file is names.dat, and exists on the disk in the form produced by CREATE. The input 
values, 

B *E 

set lower to B and upper to E and cause RETRIEVE to list only Donna Harris. The 
second console input line sets lower to B and upper to K. This causes RETRIEVE to 
list Donna Harris and John Robinson. The comma in the next input value sets the 
lower bound at AAA... A and the upper bound as K. Thus RETRIEVE lists Arthur 
Jackson, Donna Harris, and John Robinson. The last entry consists only of a comma 
pair, leaving the lower bound as the sequence AAA.. .A and the upper bound at zzz...z. 
These two bounds include the entire alphabetic range, so that RETRIEVE displays the 
entire list of names and addresses. Finally, entering EOF ends the program. 

Line 26 of Listing 8-6 opens the SYSPRINT file with the PRINT attribute and title 
of $CON. It is good programming practice to open all files with explicit attributes. In 
this case the statement is redundant because when PL/I executes the PUT LIST statement 
on line 27, it supplies the same attributes to the file by default. 
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A> ret ri eve 

Name and Address Retrieval* File Name: names. dat 



Type Lower* Upper Bounds: 6>E 



Donna Harris 
2999 Serra Rd. 
Chico Ca. 
95926 
G35-3570 

Type Lower* Upper Bounds: B >K 



Donna Harris 
2999 Serra Rd. 
Chico Ca. 
95926 
635-3570 



John Robinson 
805 Franklin St. 
Monterey Ca. 

93940 
649-1000 



Type Lower* Upper Bounds: 



Arthur JacKson 
100 W. 3rd St. 
F resno Ca . 
93706 
529-1277 



Donna Harris 
2999 Serra Rd, 
Chico Ca. 
95926 
635-3570 

Listing 8-7. Interaction with the RETRIEVE Program 
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John Robinson 
805 FranKlin St. 
Monterey Ca. 

33940 
649-1000 

Type Louert Upper Bounds: 



Arthur Jackson 
100 W. 3rd St, 
Fresno Ca . 
9370G 
529-1277 



Donna Harris 
2999 Serra Rd, 
Ch i ca Ca , 
95926 
635-3570 



John Robinson 
805 Franklin St, 
Monte rey Ca , 

93940 
649-1000 



Virginia Wilson 
? 

Unknown Can't Find 
99999 



Type Louert Upper Bounds: EOF i > 



Listing 8-7. (continued) 
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8.3 An Information management System 

The next four sample programs provide a model for an information management 
system. These programs manage a file of employee names, addresses, wage schedules, 
and wage reporting mechanisms. Each of these programs is simple, but together they 
contain all the elements of a more advanced data base management system. They 
demonstrate the power of the PL/I programming system, while providing the basis for 
custom application programs. 

First, the ENTER program establishes the data base. A second program, called 
KEYFILE, reads this data base and prepares a key file for direct access to individual 
records in the data base. A third program, called UPDATE, interacts with the user at 
the console and allows access to the data base for retrieval and update. Finally, the 
REPORT program reads the data base to produce a report. 

8.3.1 The ENTER Program 

Listing 8-8 shows the ENTER program. The ENTER program interacts with the 
user at the console and constructs the initial data base. The basic input loop between 
lines 40 and 53 prompts the user for an employee name, age, and hourly wage. ENTER 
fills the employee data structure with this information. In the example, line 48 fills the 
address fields with default values defined in the structure on lines 24 through 33. You 
can terminate the console input by entering EOF. 

The employee record contains several fields whose total length is 101 bytes. You 
can use the $S Compiler switch to verify this value. The OPEN statement on line 37 
specifies a fixed record size of 128 bytes, so you can expand the records later. Each 
record of the emp file holds exactly one employee data structure. 

The OPEN statement gives emp the KEYED attribute, and makes each record the 
fixed size specified in the ENVIRONMENT option. The OPEN statement also specifies 
the buffer size as 8000 bytes, which PL/I automatically rounds off to 8192 bytes. The 
program fills each employee record from the console input and writes the record to 
the employee file named in the command line, with the file type EMP, line 38. 

The WRITE statement is in a separate subroutine, named WRITE-IT, starting on line 
55. Placing the code in a separate subroutine helps reduce the size of the program because 
the program calls WRITE-IT at two different points, lines 45 and 52. 
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Listing 8-9 shows the user interaction with the ENTER program as several employee 
records are entered. Entering EOF ends the program, closes the file plantl.emp, and 
records the data on the disk. 

1 a /****#*#************##*#♦*###***•*******#****#*#*##**/ 

2 a /* This program constructs a data base of employee */ 

3 a /* records usinsf a structure declaration. */ 

4 a /*#**##*#*####**######**##■#*******##*#**#####*#*####/ 

5 a 

6 a 



7 b 

8 b 

9 b 

10 b 

11 b 

12 b 

13 b 

14 b 

15 b 
IB b 

17 b 

18 b 

19 b 

20 b 

21 b 

22 b 

23 b 

24 b 

25 b 

26 b 

27 b 

28 b 

29 b 

30 b 

31 b 

32 b 

33 b 

34 b 

35 b 

36 b 

37 b 

38 b 

39 b 



enter: 

procedure opt ions ( wain ) ! 
2 repl ace 

t rue by x 1 ' b * 

false by '0'b i 

declare 

1 employee static* 

2 name cha rac te r ( 30 ) uaryinS* 
2 add ress * 

3 street cha racte r (30 ) uaryinS* 

3 city character(lO) u a r y i n 3 * 

3 state cha racte r ( 12 ) varying* 

3 zip fixed decimal(5)t 

2 aUe fixed dec ima 1 ( 3 ) * 

2 wa3e fixed dec ima 1 ( 5 *2 ) * 

2 hours fixed dec ima 1 ( 5 * 1 ) i 

declare 

1 default static* 

2 street characte r (30) varying 

in i t i al ( v ( no street)')* 
2 city cha rac te r ( 10) varying 

in i t i al ( Mno city)')* 
2 state ch a rac te r ( 12) varying 

initial^ (no state)')* 
2 zip fixed decimal (5) 
initial (00000) 5 
declare 

emp file! 

open file(emp) keyed output env i ronment ( f ( 128 ) »b ( 8000 ) ) 
title ( V *1.EMP') 5 



Listing 8-8. The ENTER Program 
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40 


c 






do 


wh i le ( t rue ) 5 


41 


c 








put 1 i st ( * EmpI o y ee : ' ) i 


42 


c 








Set 1 i st ( name ) 5 


43 


c 








if name = x E0F' then 


44 


d 








do ; 


45 


d 








call write i t ( ) i 


46 


d 








stop ; 


47 


d 








end i 


48 


c 








address = default! 


49 


c 








put list {' ASe > WaSe: ' ) 5 


50 


c 








Set list ( aSe twase ) i 


51 


c 








hours = 05 


52 


c 








call write i t ( ) ! 


53 


c 






en 


di 


54 


b 








55 


b 






write it: 


56 


c 








procedure ! 


57 


c 








write file(emp) f rom ( empl oy ee ) 5 


58 


c 






en 


d write it! 


59 


b 








60 


b 


— e 


rid 


e n t e r i 



Listing 8-8. (continued) 



A > e n t e r plant 1 
Employee: Jackson 

ASe > WaSe: 25 1 G, 75 
Employee: Harris 

A Set WaSe: 30 > 9,00 
Employee: Robinson 

A5e» WaSe: Hi > 15,00 
Employee: Nil son 

ASet WaSe: 27 > 7,50 
Employee: Smith 

A Set WaSe: 25 t > 
Employee: Jones 

ASe t WaSe : t > 
Employee: EOF 
A> 



Listing 8-9. Interaction with the ENTER Program 
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8.3.2 The KEYFILE Program 

Listing 8-10 shows the KEYFILE program, which constructs a key file by reading 
the data base file created by ENTER. The key file is a sequence of entries consisting 
of an employee name followed by the key number corresponding to that name. In this 
case, the key file is also a STREAM file, so you can display it at the console. Line 16 
opens the $1.EMP file with the KEYED attribute, specifies each record to be 128 bytes 
long, and sets a buffer size of 10000 bytes. Line 19 opens the key file named keys as 
a STREAM file with LINESIZE(60) and a TITLE option that appends KEY as the 
filetype. 

On line 23, the KEYFILE program reads successive records, extracts the key with 
the KEYTO option, and writes the name and key to both the console and to the key 
file. The sample interaction in Listing 8-11 illustrates the output from KEYFILE using 
the plantl.emp data base. Each key value extracted by the READ statement is the 
relative record number corresponding to the position of the record in the file. 

After executing the KEYFILE program, you can use the command 

A > type pi ant 1 * Key 

to display the actual contents of the plantl.key file as shown in Listing 8-12. 

1 a /###**##***##*##**#*###*#####**#**#*#**#**###******#**#*/ 

2 a /* This program reads an employee record file and */ 
3a /* creates another file of keys to access the records. */ 
4 a /#**#*##*******#*###****#*#**##**###***#***#*****#*##***/ 



5 a 

6 a 

7 b 

8 b 

9 b 

10 b 

11 b 

12 b 

13 b 

14 b 

15 b 
IB b 

17 b 

18 b 

19 b 

20 b 

21 b 



Kevf ile; 

procedure opt i ons ( wain ) ! 
declare 

1 employee static* 

2 natne cha rac t e r ( 30 ) u a rv in i i 

declare 

< in put » Keys) filet 
k fixedi 

open file(input) keyed enui ronment ( f ( 128) tb ( 10000 ) ) 
t i 1 1 e ( * $1 . emp ' ) i 

open file(keys) stream output 

linesize(BO) title('$l.key'); 



Listing 8-10. The KEYFILE Program 
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22 c 






do 


while('l') i 




23 c 








read f i 1 e ( input ) into ( employee ) 


keyto(k) ; 


24 c 








put skip 1 ist ( K >name ) ? 




25 c 








put file(Kevs) 1 i st ( name >k ) 5 




26 c 








if name = 'EOF' then 




27 c 








stop i 




28 c 






enc 


; 




29 b 










30 b 


— e 


nd 


key 


f ile i 





A>A'e>'fiie plantl 

Jackson 

1 Harris 

2 Robinson 

3 Wilson 

4 Smith 

5 Jones 
B EOF 

A> 



Listing 8-10. (continued) 



Listing 8-11. Interaction with the KEYFILE Program 



A>£ype plantl , Key 
'Jackson ' 'Harris' 
'Wilson ' 3 'Smith ' 4 
6 



1 'Robinson ' 
Jones ' 5'EOF 



Listing 8-12. Contents of the Key File 

8.3.3 The UPDATE Program 

The UPDATE program in Listing 8-13 allows you to access the data base created 
by ENTER and indexed through the file created by KEYFILE. The UPDATE program 
first reads the key file, a STREAM file, into a data structure called keylist. Keylist cross- 
references the employee name with the corresponding key value in the data base. Lines 
20 to 23 declare the data structure that holds these cross-reference values, and lines 
37 to 40 fill in the data. 

Note: line 39 is not a multiple assignment statement, but rather a definition of a Boolean 
expression for the variable, eolist. 
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UPDATE opens the emp file on line 31. The OPEN statement assigns the file the 
DIRECT attribute, that allows both READ and WRITE operations with the individual 
records identified by a key value. You then enter an employee name as matchname, 
and the DO-group between lines 47 and 61 directly accesses the individual records in 
the data base. 

The direct access takes place as follows. Line 48 searches the list of names read from 
the key file. If there is a match, the READ with KEY statement on line 50 brings the 
employee record into memory from the emp file. The program displays and updates 
various fields from the console, and then rewrites the record to the data base with the 
WRITE with KEYFROM statement on line 58. UPDATE ends execution when you 
enter an EOF. 

Listing 8-14 shows three successive update sessions during which various addresses 
and work times are updated. In each session, you enter the employee name, access and 
display the record, and optionally, update the fields. The GET LIST statement is useful 
here. To change a value, you simply type the new value in the field position. If you do 
not want to change a value, entering a comma delimiter leaves the field unchanged. 

1 a /**#*#**##*#***###*###******##***#**#*****#*#**#***#**/ 

2 a /* This program allows you to retrieve and update */ 
3a /* individual records in an employee data base usinS */ 

4 a /* a Keyed f ile , */ 

5 a /****#*#**##**##**##*##*#*****######*##******#*##*#***/ 
,— update : 

procedure opt ions (Main ) i 
declare 

1 employ ee static » 

2 name charact e r( 30) varying* 
2 add ress t 

3 street charac te r ( 30) varying* 
3 city character(lO) v a r y i n 3 t 
3 state character(12) varyinSt 
3 zip fixed decimal (5) > 
2 a$e fixed decimal (3) > 
2 waSe fixed dec imal (5 >2 ) t 
2 hours fixed decimal (5 1 1 ) 5 

declare 

1 Keylist(lOO) » 

2 Keyname cha rac te r (30 ) varying 
2 Keyual fixed binary? 



7 


d 

b 


8 


b 


3 


b 


10 


b 


11 


b 


12 


b 


13 


b 


1-3 


b 


15 


b 


IB 


b 


17 


b 


18 


b 


13 


b 


20 


b 


21 


b 


22 


b 


23 


b 


24 


b 



Listing 8-13. The UPDATE Program 
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25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
GO 
61 
62 
63 
64 



declare 

(it endlist) fixed* 
eolist bit(l) static in i t ial ( '0 ' b ) * 
matchname charact e r ( 30 ) varying 
( ewp * keys ) file! 

open file(ewp) update direct env i ronment ( f ( 128 ) ) 
title r$l,EMP') i 

open file(keys) stream env i ronmen t ( b ( 4000 ) ) 
t i 1 1 e ( % $ 1 , k e y ' ) i 

do i = 1 to 100 while ( "eolist ) i 

Set file (keys) list(keyname(i)»keyval(i))5 

eolist = keynaine(i) = 'EOF'i 
end i 



do w 
p 
i 



hi le < 

ut sk 
et li 
f mat 

s to 
o i = 

if 



v l'b) i 

ip list( v Employee: ')! 
st (matchname ) i 
chname = 'EOF' then 
p 5 

1 to 100! 
matchname = keyname(i) then 
do I 

read file(emp) into ( empl oyee ) 

key(keyval(i))5 
put skip 1 ist ( ' Add ress : '» 

street* city* state* zip)i 
put sKip list( % ')! 
Set list(street» city* state* zip)? 
put 1 i st ( v Hours : ' »hou rs > 
Set 1 i st ( hou rs ) 5 
write file(emp) from (employee) 
Keyfrom(keyval(i))i 
end ! 



end 5 



nd 5 



end update ! 



Listing 8-13. (continued) 
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{\>update plantl 

Employee: JacA'son 

Address: (no street) (no city) (no state) 

'100 U, 3rd St,' i 'Fresno', 'Ca,'> 9370B 
Hours: 0.0 : 40,0 

Employee: Harris 

Address: (no street) (no city) (no state) 

'2999 Serra Rd,'» 'Chico', 'Ca,', 95326 
Hours: 0.0 : 46. 

Employee: EOF 

f\>update plantl 

Employee: Harris 

Address: 2999 Serra Rd. Chico Ca. 9592B 

Hours: 46.0 : 40,0 

Employee: Mil son 

Address: (no street) (no city) (no state) 

Hours: 0.0 : 35,5 

Employee: EOF 

f\>update plantl 

Employee: Hi Is on 

Address: (no street) (no city) (no state) 

'55B Palm Ave,', 'BurbanK', 'Ca,', 91507 
Hours: 35.5 : , 

Employee: EOF 
A> 

Listing 8-14. Interaction with the UPDATE Program 
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8.3.4 The REPORT Program 

Listing 8-15 shows the REPORT program. The REPORT program uses the updated 
employee file to produce a list of employees along with their paycheck values. The 
REPORT program also accesses the employee file, but it reads the file sequentially to 
produce the desired output. The main DO-group between lines 35 and 5 1 reads each 
successive employee record and constructs a title line of the form, 

[name] 

followed by a dollar amount. REPORT uses the STREAM form of the WRITE 
statement, lines 41 and 50, to produce the output line. Line 40 includes the embedded 
control characters A M and A J at the end of buff to cause a carriage return and line-feed 
when writing the buffer. The REPORT program then computes the pay value and 
assigns it to the CHARACTER- VARYING string called buff, on line 44. In this 
assignment, PL/I performs an automatic data conversion from FIXED DECIMAL to 
CHARACTER, with leading blanks. REPORT also scans the leading blanks, replacing 
them by a dollar sign dash sequence to align the output, and writes the data to the report 
file. 

Listings 8-16 and 8-17 show the output from the REPORT program. In the first 
case, the command, 

A > r 6 p a r t plantl $c on 

sends the report to the console for review. In the second case, the command, 

A> repo rt plantl plantl*prn 

sends the output to the disk file plantl. prn. You can then examine the contents of the 
file with the command: 

A > t y p e plantltPrn 
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1 a 



3 


a 


a 


a 


5 


a 


G 


b 


7 


b 


8 


b 


9 


b 


10 


b 


11 


b 


12 


b 


13 


b 


14 


b 


15 


b 


IB 


b 


17 


b 


18 


b 


19 


b 


20 


b 


21 


b 


22 


b 


23 


b 


24 


b 


25 


b 


28 


b 


27 


b 


28 


b 


29 


b 


30 


b 


31 


b 


32 


b 


33 


b 


34 


b 



/ * This program reads an employee data base and # / 
/* prints a list of paychecks. * / 

repo rt : 

procedure oPtions(main)5 
declare 

1 employee static* 

2 name cha racte r ( 30 ) uar/inSt 
2 address* 

3 street c h a r a c t e r ( 3 ) u a r y i n 3 > 

3 city c h a r a c t e r ( 1 ) varying* 

3 state c h a r a c t e r ( i 2 ) u a r y i n 3 » 

3 zip fixed decimal (5) > 

2 a 3 e fixed d e c i m a 1 ( 3 ) t 

2 w a 3 e fixed decimal (5*2) t 

2 hours fixed d e c i m a 1 ( 5 * 1 ) i 

declare 

i fixed* 

dashes character(15) static initial 
( *$ ') , 

.buff c h a r a c t e r ( 2 ) u a r y i n a > 
( 3 r o s s p a y t withhold) fixed d e c i m a 1 ( 7 j 2 ) > 
(repfile; empfile) file! 

open f i le ( empf i le ) Keyed enu i ronment ( f ( 128 ) »b ( 4000 ) ) 

title (Hl.EMP')i 
open f i 1 e ( repf i 1 e ) stream print enu i ronment ( b ( 2000 ) ) 

t itle ( x $2.*2' ) ! 

put 1 i s t ( ' S e t Top of Forms* Press Return')! 
Set skip? 



Listing 8-15. The REPORT Program 
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35 c 




1 — c 





whi le ( 


36 c 






read f 


37 c 






if nam 


38 c 






sto 


39 c 






put fi 


40 c 






buff = 


41 c 






write 


42 c 






Srossp 


43 c 






wi thho 


44 c 






buff = 


45 d 








do i = 


46 d 








whi 


47 d 








end ! 


48 c 








i = i 


49 c 






subst r 


50 c 






write 


51 c 




— en 


d! 


52 b 






53 b 


— er 


d i 


epo rt i 



M'b) ; 

i le ( empf i le ) in to ( empl oy ee ) i 

e = 'EOF' then 

p ; 

le( repf i le) sKip(2) i 

1 [ * ! ! naine ! ! ' ] " m" J ' 5 
filet repf ile) from (buff) i 
ay = watfe * hours? 
Id = Srosspay * .15! 

Srosspay - withhold! 

1 to 15 
le (substr(buf f »i ,1 ) 



') i 



- 1 ! 

(buff»l»i) = subst r(dashes tl ti ) i 

file ( repf ile) f row(buf f ) i 



Listing 8-15. (continued) 



A>report plantl $con 

5et Top of Forms» Press Return 

[Jackson ] 
$ 229.50 

[Harris] 
$ 351.90 

[Robinson] 
$ o.OO 

[Wilson] 
$ 226.32 

[Smith] 

$ 0.00 

[Jones] 

$ 0.00 

A> 

Listing 8-16. REPORT Generation to the Console 
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A>report p 1 an 1 1 plantl.prn 
Bet Top of Forhist Press Return 

A > type plantl.prn 

[JacKson] 
$ 229,50 

[Harris] 

* 351 .90 



[Robinson] 
$ 0,00 



[Wilson] 

$ 226,32 



[Smith] 

$ o.OO 



[Jones ] 

$ 0.00 



Listing 8-17. REPORT Generation to a Disk File 

End of Section 8 
References: Sections 10.1, 10.8, 11.2, 12 LRM 
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Section 9 

Label Constants, Variables, and 

Parameters 



Each of the programs presented so far ends execution either by encountering an end- 
of-file condition with a corresponding ENDFILE traceback, or by using a special data 
value that signals the end-of-data condition. The EPOLY program detects the end-of- 
data condition by checking for the special case where all three input values, x, y, and 
z, are zero. 

Fortunately, PL/I provides more elegant ways to sense the end-of-data condition. In 
fact, sensing the end-of-data condition is just one of many facilities under the general 
heading of condition processing. Most often, handling these conditions involves labeled 
statements. You need some background in label processing before you take up the 
general topic of condition processing in Section 10. 



9.1 Labeled Statements 

It is an axiom of programming to avoid labeled statements and GOTOs because of 
the unstructured programs that result. Programs containing many labeled statements 
are often difficult for other programmers to comprehend. Such programs become 
unreadable, even to the author, as the program grows in size. 

PL/I encourages good structure by providing a comprehensive set of control structures 
in the form of iterative DO-groups with REPEAT and WHILE options. These control 
structures preclude the necessity for labeled statements in the general programming 
schema. You should use these control structures whenever possible, and limit the use 
of labeled statements to condition processing and locally-defined, computed GOTOs. 

Judicious use of labeled statements is appropriate in condition processing. The occur- 
rence of an error, such as a mistyped input data line, is easily handled by transferring 
program control to a label in an outer block, where recovery takes place. This method 
of understanding the program flow is simpler than the usual system of flags, tests, and 
return statements. 
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9.2 Program Labels 

Program labels, like other PL/I data types, fall into two broad categories: label 
constants and label variables. A label constant appears literally within the source 
program, and its value does not change during program execution. A label variable 
has no initial value, and you must assign it the value of a label constant through a 
direct assignment statement, or through the parameter assignments implicit in a sub- 
routine call. 

The following code sequence is an example of a label constant preceding a PL/I 
statement. 

on error(i) 
b e 3 i n 5 

put skip 1 i s t ( s B a d Input* Try A 3 a i n ' ) 5 

Soto retry? 
e n d i 



retry: Set 1 i s t ( n a m e ) i 



The statement on error(l) sets a trap for a particular condition. If the condition 
arises due to an invalid input, then control transfers to the BEGIN block, which 
outputs an error message, and then transfers control back to the labeled statement. 
If there is no error on input, control transfers to the next statement following the 
GET LIST statement. 



102 



PL/I Programming Guide 9.3 Computed GOTO 

9.3 Computed GOTO 

In PL/I, a label constant can contain a single positive or negative literal subscript. 
A subscripted label constant corresponds to the target of an n-way branch, that is, a 
computed GOTO. The following code sequence shows a specific example. 

Set 1 i st ( x ) 5 
So to q ( x ) 5 
q(-l ) : 

v = f 1 ( x ) ; 
Soto e n d q ! 
q ( ) : 

y = f 2 ( x ) 5 

Soto e n d q 5 
q(2) : 5 
q(3) : 

y = f 3 ( x ) 5 
e n d q : 
put skip 1 i s t ( x f ( x ) = ' * y ) 5 



This code implicitly defines four label constants: q(-l), q(0), q(2), and q(3). The Com- 
piler automatically defines an internal label constant vector, 

q ( - 1 : 3 ) label constant 

to hold the values of these label constants. 

The preceding statement is not a valid PL/I statement, but indicates what the Compiler 
does internally when it encounters such statements in the source code. Also, when 
using such constructs, do not transfer control to a subscript that does not have a 
corresponding label-constant value. In the preceding case, a branch to q(l) produces 
undefined results. 
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9.4 Label References 

A reference to a label constant can be either local or nonlocal. A local reference to 
a label constant means that the label occurs as the target of a GOTO statement only 
in the PROCEDURE or BEGIN block that contains the GOTO. A nonlocal reference 
to a label constant means that the label occurs on the right side of an assignment to 
a label variable, as an actual parameter to a subroutine, or as the target of a GOTO 
statement in an inner nested PROCEDURE or BEGIN block. 

Although there is no functional difference between processing a locally-referenced 
and nonlocally-referenced label constant, a nonlocal reference requires additional space 
and time. For this reason, PL/I assumes that a subscripted label constant will be only 
locally referenced. If program control transfers to a subscripted label constant from 
outside the current environment, undefined results can occur. 

As an example, consider the following code sequence: 

• m a i n : 

procedure optionsdnain) 5 
PI : 

procedure 5 
«f o t o 1 a b 1 5 
Soto lab 2 5 
-P2: 

procedure 5 
Soto lab 25 
-end P2 ? 
1 a b 1 : 5 
1 a b 2 : 5 
1 — end P 1 5 
e n d w a i n 5 

The label constant labl is only locally referenced in the procedure PI, while lab2 is 
the target of both a local reference in PI and a nonlocal reference in P2. 
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9.5 Example Program 

Listing 9-1 shows a nonfunctional program that illustrates the use of various label 
constants and variables. The label constants in the LABELS program are c(l), c(2), 
c(3), labl, and lab2. They are defined by their literal occurrence in the program. The 
label variables are x, y, z, and g, and are defined by the declarations on lines 10 and 
38. 

At the start of execution, the label variables have undefined values. The program 
first assigns the constant value labl to the variable x. Label variable y then indirectly 
receives the constant value labl through the assignment on line 12. As a result, all 
three GOTO statements on lines 14, 15, and 16 are functionally equivalent. Each 
statement transfers control to the null statement following the label labl on line 32. 

The subroutine call on line 18 shows a different form of variable assignment. Lab2 
is an actual parameter sent to the procedure P, and assigned to the formal label variable 
g. In this program, the subroutine call transfers program control directly to the state- 
ment labeled labl. 

The DO-group beginning on line 20 initializes the variable label vector z to the 
corresponding constant label vector values of c. Due to this initialization, the two 
computed GOTO statements, starting on line 25, have exactly the same effect. 
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a 
b 


8 


b 


9 


b 


10 


b 


11 


b 


12 


b 


13 


b 


14 


b 


15 


b 


16 


b 


17 


b 


18 


b 


19 


b 



/* This is a nonfunctional programs Its purpose is #/' 
/ * to illustrate the concept of label constants and # / 
/* variables. * / 

Labels: 

procedure optionsUiain) 5 
declare 
i f i >< e d > 

(m y > z ( 3 ) ) label! 
x = labl! 
y = x 5 

Soto 1 ab 1 5 
Soto X 5 
Soto y i 

call P(lab2) i 



Listing 9-1. An Illustration of Label Variables and Constants 
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20 c 




— do i = 1 to 


31 


21 c 




z ( i ) = c 


i) 5 


22 c 




— end j 




23 b 






2a b 


i = 25 




25 b 


Soto z ( i ) ; 




2G b 


Soto c ( i ) 5 




27 b 






28 b 


o(l): ; 




29 b 


c(2): i 




30 b 


c(3): i 




31 b 






32 b 


labl: i 




33 b 


lab2: 5 




34 b 






35 b 




-P: 




36 c 




procedure 


(3) i 


37 c 




declare 




38 c 




i label 




39 c 




Soto 3 ! 




40 c 




— end P5 




41 b 






42 b 


— end I 


.abels i 





Listing 9-1. (continued) 

End of Section 9 



References: Sections 3.3, 8.5 LRM 
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Section 10 
Condition Processing 



Condition processing is an important facility of any production programming lan- 
guage. The language should allow a program to intercept and handle run-time error 
conditions with program-defined actions, and then continue execution. 

For example, a common condition occurs when a program is reading input data 
from an interactive console, and you inadvertently enter a value that does not conform 
to the data type of the input variable. The PL/I run-time system signals a conversion 
error, and in the absence of any program-defined action, ends program execution with 
a traceback. If this premature termination occurs after hours of data entry, it causes 
a considerable amount of wasted effort. This is unacceptable in a production environment. 



10.1 Condition Categories 

PL/I provides nine categories of conditions. They are: 

■ ERROR 

■ FIXEDOVERFLOW 

■ OVERFLOW 

■ UNDERFLOW 

■ ZERODIVIDE 

■ ENDFILE 

■ UNDEFINEDFILE 

■ KEY 

■ ENDPAGE 

The first five categories include all arithmetic error conditions and miscellaneous 
conditions that can arise during I/O setup and processing. They also include conversion 
errors between the various data types. The last four categories apply to a specific file 
that the run-time I/O system is accessing. Each condition has an associated subcode 
that provides information about the source of the condition. 
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10.2 Condition Processing Statements 

The ON, REVERT, and SIGNAL statements implement condition processing in 
PL/I. The ON statement defines the actions that take place upon encountering a con- 
dition. The REVERT statement disables the ON statement, and recovers any previously 
stacked condition. The SIGNAL statement allows your program to signal various 
conditions. 

10.2.1 ON and REVERT 

The following code sequence illustrates the ON and REVERT statements inside a 
DO-group. 

do while* M 'b) 5 

on e n d f i 1 e ( s v s i n ) 
EOF = x 1 ' b » 



revert endfile(sysin) 5 
e n d ! 

Here, both the ON and the REVERT statement execute on each iteration. Processing 
the ON and REVERT statements involves run-time overhead. To avoid this, code the 
same DO-group as follows: 

on e n d f i 1 e ( s y s i n ) 

EOF = x 1 'b 5 

do w h i 1 e ( M ' b ) 5 



end 5 

PL/I automatically executes the REVERT statement for any ON conditions that you 
enable inside a procedure block when control passes outside the block. The program 
shown in Listing 10-1 illustrates this concept. 
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1 a 

2 a 

3 a 
a a 
5 a 
G a 
7 b 
B b 
9 b 

10 b 

11 b 



/* This proSraM is nonfunctional. Its purpose is to */ 
/* illustrate how PL/I executes the ON and REVERT */ 
/* statement s ♦ */ 

/#*#****#**»*****##***####**♦*#**#***#***##*♦*#*##**#*/ 
auto_reuert: 

procedure options(main)! 
declare 
i fixed* 
sysin file! 



12 c 




—do i = 1 to 10000 5 




13 c 




call P(itexit)! 




14 c 




exit: 




15 c 




— end i 




IB b 






17 b 




r p: 




18 c 




procedure (index flab) 5 




19 c 




declare 




20 c 




(t i index) fixed* 




21 c 




lab label i 




22 c 








23 c 




on endfile(sysin) 




24 c 




Soto lab! 




25 c 








2B c 




put sKip list(ind ex »*:')! 




27 c 




set list ( t ) i 




28 c 




if t = index then 




29 c 




Soto 1 a b ! 




30 c 




- end P! /# implicit REVERT supp 


i ed here */ 


31 b 






32 b 


— en 


d auto reuertJ 





Listing 10-1. The REVERT Program 

In the REVERT program, line 13 calls the procedure P and passes to it the actual 
parameters i, the DO-group index, and the label constant exit. The ON statement 
inside P executes every time the procedure is called. If PL/I did not supply the REVERT 
statement automatically, the Condition Stack would overflow when the value of the 
index count reached 17. Thus, REVERT has three possible ways to exit the procedure 
P. 

If you enter an end-of-file character, CTRL-Z, REVERT executes the enabled ON 
condition and sends control through the label variable lab to the statement labeled 
exit. PL/I deactivates the procedure and executes the REVERT statement because the 
GOTO statement transfers control outside the environment of P. 
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The second possible exit follows the test on line 28. If you enter a value equal to 
the index, then the GOTO statement on line 29 executes and again sends control 
outside the environment of P. 

Finally, if control reaches the end of P, PL/I executes the REVERT statement and 
disables the ON condition set on line 23. No matter how control leaves the environment 
of the procedure, PL/I always disables the ON condition. 

10.2.2 SIGNAL 

The SIGNAL statement activates the ON-body, the body of statements corresponding 
to a particular ON statement. Thus, processing a SIGNAL statement has the same 
effect as when the run-time system signals the condition. 

The following code sequence illustrates the SIGNAL statement. 

on e n d f i 1 e ( s y s i n ) 
stop? 

do w h i 1 e < M ' b ) 5 

sfetlist(buff)? 

if buff = S END' then 

signal e n d f i 1 e ( s v s i n ) 5 

put skip 1 i s t ( b u f f ) i 
e n d 5 



This code executes the SIGNAL statement whenever the GET LIST statement reads 
the value END from the file SYSIN. Thus, the ON condition receives control on a real 
end-of-file, or when the value END is read. 



10.3 Examples of Condition Processing 

The following two programs, FLTPOLY2 and COPYLPT, incorporate some con- 
dition processing, so you can see how these concepts are implemented. 
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10.3.1 The FLTPOLY2 Program 

Listing 10-2 shows the FLTPOLY2 program. This is essentially the same program 
listed in Section 7-1. The only difference is that it incorporates condition processing 
to intercept the end-of-file condition for the file SYSIN. If you run this program, you 
will see how you can end execution with a CTRL-Z character. Unlike FLTPOLY, if 
you enter all zeros, FLTPOLY2 simply evaluates the polynomial and prompts you for 
more input. 



l 

2 

3 

4 

5 

6 

7 

8 

9 
10 
11 
12 

13 b 

14 b 

15 b 



/****#***#*****#********#*♦*###***#********#*#******#***/ 
/* This program evaluates a polynomial expression */ 
/* using- FLOAT BINARY data. It also traps the end-of- */ 
/* file condition for the file SYSIN, */ 

f ltPol/2: 

procedure opt i ons ( main ) i 
1 repl ace 

false by v 0'b t 
true by M'bi 
declare 

(xiviz) float binary (24) » 

eofile bit(l) static ini ti al ( false ) » 

sysin file? 



IS b 




on endfile(sysin) 


17 b 


eofile = true; 


18 b 




19 c 




r— do whi 1 e ( t rue ) i 


20 c 




put skip(2) 1 i s t ( K T y p e x t y » z : ' ) i 


21 c 




Set 1 ist ( x >y >z ) 5 


22 c 






23 c 




if eofile then 


24 c 




s top i 


25 c 






2G c 




put skip list ( v 2' ) i 


27 c 




put skip 1 i s t ( v x + 2y + z = ' »P ( x >y »z ) ) » 


28 c 




— end i 


29 b 




30 b 




- P: 


31 c 




procedure (x>y»z) returns (float binary(24))i 


32 c 




declare 


33 c 




(x »y tz) float binary (24) j 


34 c 




return (x * x + 2 * y + z)j 


35 c 




— end Pi 


36 b 




37 b 


— end f ltPol/2! 






Listing 10-2. The FLTPOLY2 Program 
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10.3.2 The COPYLPT Program 

Listing 10-3 shows an example of I/O processing using ON conditions. The COPYLPT 
program copies a STREAM file from the disk to a PRINT file, while properly formatting 
the output line with a page header and line numbers. The program accepts console 
input to obtain the parameters for the copy operation, and provides error exits and 
retry operations for each input value. COPYLPT sets up various ON-units to intercept 
errors during the copy operation that takes place in the iterative DO-group between 
lines 71 and 76. The following sections discuss the individual parts of the program. 

/******##******#****#####**#*##*#*****###****#####*/ 
/* This prosram copies a STREAM file on disk to a */ 
/* PRINT file* and formats the output with a paSe */ 
/* header* and line numbers. */ 

/*#*#***#**#*************##*****####*#*##*#***#**##/ 
copy: procedure options(fnain)5 

declare 

(sysin* sourcefile* printfile) file* 

(paSesize* pasewidth* spaces* 1 inenumbe r) fixed* 

(line characte r ( 14) » buff cha racte r ( 254 ) ) varyins? 

put list(' A z File to Print Copy Program') 5 

on endfile(sysin) 
So to typeoue r i 

typeouer: 

put sKip(5) lisUHow Many Lines Per PaSe? ')! 
Set 1 ist ( paSesize ) 5 

put skip list('How Many Column Positions? ')» 
set skip 1 i st ( pasewidth ) 5 

on e rro r( 1 ) 
beSin ! 

put list (* Invalid Number* Type Integer')! 
So to Setnumbe r i 
end 5 
Setnumbe r: 

put skip lisU'Line Spacing (l=SinSle)? ')5 
Set skip 1 i st ( spaces ) 5 
reve rt e rro r( 1 ) ! 

put skip list ( 'Destination Device/File: ')5 
set skip list(line)! 



1 


a 


2 


a 


3 


a 


a 


a 


5 


a 


6 


b 


7 


b 


8 


b 


9 


b 


10 


b 


11 


b 


12 
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Listing 10-3. The COPYLPT Program 
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44 
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43 
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63 
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64 


c 


65 


c 


66 


c 


67 


c 


68 


c 


68 


b 


70 


b 


71 


c 


72 


c 


73 


c 


74 


c 


75 


c 


76 


c 


77 
7R 


b 
h 



open f i le ( printf i le ) print paSes i ze ( paies i ze ) 
1 ines ize ( paSewidth ) title(line)! 



on un 
be 



i— en 
ret ry 

PU 

Se 

OP 

on en 

r- be 



definedfile(sourcefile) 

Sin 5 

put skip 1 i st ( ' " ' 1 1 ine > v " isn''t a Ualid Name')! 

So to ret ry i 

di 



') ; 

eny i ronment(b(8000) 



t skip listrSource File to Print? 

t 1 ist ( 1 ine ) 5 

en f i le ( sourcef i le ) streaui 

title(line) ! 
dfile(sourcefile) 
Sin 5 

put f i le ( printf i le ) paSei 
s top ! 

d; 



on endfile(printfile) 
be sin ! 

put skip list( ' "S" S"S"S Disk is Full')! 
stop ? 
1 — end! 

on endpaSe ( printf i le ) 
b e s i n ! 

put f ile(printf ile) paSe skip(2) 

1 ist ( 'PAGE' tpaseno(printfile)) i 
put f ile(printf ile ) skip(fl)! 
e*nd 5 

siSnal endpaSe ( printf i le ) ! 

do linenumber = 1 repeat ( 1 inenumbe r + l)i 

Set file (sourcefile) edit(buff) (a)i 

put file ( printf i le ) 

editdinenumbert' ! ' tbuff) (f(5) »x( 1 ) »a(2) »a) ! 

put file (printfile) skip( spaces ) i 
end 5 



end copy? 



Listing 10-3. (continued) 
The COPYLPT program begins by reading five values: 

■ the number of lines on each page 

■ the width of the printer line 
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■ the line spacing, normally single- or double-spaced output 

■ the destination file or device 

■ the source file or device 

While entering these parameters, you can type an end-of-file CTRL-Z character and 
restart the prompting. 

The PUT LIST statement on line 13 writes the initial sign-on message. Recall that 
PL/I allows control characters in string constants. Here, the first character of the message 
is a CTRL-Z, which clears the screen if you are using an ADM-3A™ CRT device. If 
you are using some other device, you can substitute the proper character and recompile 
the program. 

The ON statement of line 15 traps the ENDFILE condition for the file SYSIN, so 
that execution begins at typeover whenever the console reads an end-of-file character. 

Lines 19 through 23 read the first two parameters with no error checking other than 
detecting the end-of-file. Line 25 however, intercepts conversion errors for all operations 
that follow. If the GET statement on line 32 reads a nonnumeric field, control passes 
to the on-body between lines 26 and 29 that writes an error message, branches to 
getnumber, and retries the input operation. Following successful input of the parameter 
spaces, the REVERT statement on line 33 disables the conversion error handling. 

COPYLPT opens the input and output files between lines 38 and 50. The program 
assumes that the output file can always be opened, but detects an UNDEFINED input 
file, so you can correct the filename. 

The program executes two ON ENDFILE statements between lines 51 and 61. The 
first statement traps the input end-of-file condition and performs a page eject on the 
output file. This ensures that the printer output is at the top of a new page after 
completing the print operation. The STOP statement included in this ON-unit completes 
the processing with an exit. 

The second ON-unit intercepts the end-of-file condition on the print file. This can 
only occur if the disk file fills, so the unit prints the message, 

D i s K is Full 

and ends execution. The CTRL-G character sends a series of beeps to the CRT as an 
alarm. The run-time system closes all files upon termination, so that the print file is 
intact to the full capacity of the disk. 
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Line 63 begins an ON ENDPAGE unit that intercepts the end-of-page condition for 
the print file. Whenever the run-time system signals this condition, the ON-unit moves 
to the top of the next page, skips two lines, prints the page number, and skips four 
more lines before returning to the signal source. The SIGNAL statement on line 70 
starts the print file output on a new page by sending control to the ON-unit defined 
on line 63. All subsequent ENDPAGE signals are generated by the run-time system at 
the end of each page. 

The DO-group beginning on line 71 initializes and increments a line counter on each 
iteration. The GET EDIT statement on line 72 specifies an A, alphanumeric, format. 
This fills the buffer with the next input line up to, but not including, the carriage return 
line-feed sequence. The PUT EDIT statement on line 73 writes the line to the destination 
file with a preceding line number, a blank, a vertical bar, and another blank, resulting 
from the A(2) field. If the run-time system signals the ENDPAGE condition while 
executing the PUT statement on line 75, the format item SKIP(spaces) might not be 
processed. 

Listing 10-4 shows the user interaction with the COPYLPT program. Here, the source 
file is the LABELS. PLI program, and $LST, the physical printer, is the destination. 

A > c o p >' lpt 

File to Print Copy Program 



How Many Lines Per PaSe? 2G 

How Many Column Positions? 80 

Line Spacing ( 1 =Sin Si e ) ? Yes 
Inualid Number* Type Integer 
Line Spacing ( l = SinSle)? 1 

Destination Device/File: $lst 

Source File to Print? copy , pi 1 

" copy.pil " isn't a Valid Name 
Source File to Print? copy , pi i 

Listing 10-4. Interaction with COPYLPT 
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Listing 10-5 shows two pages of output produced by the program. 



PAGE 



3 

a 

5 

6 

7 

8 
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10 

11 

12 

13 

14 

15 

IB 

17 

18 

19 

20 



/* This program copies one file to another usintf */ 
/* buffered I/O, */ 

/ft************************************************/ 
copy : 

procedure options(main) 5 

declare 

( input_f i le toutPut_f i le ) file! 

open file (input_file) stream 

enui ronment(b(8192) ) title( v *l.$l')i 

open file ( outPut_f i le ) stream output 

environment(b(8192)) titled $2. $2' )i 
declare 

buff characte r (254) varyinsfj 

do wh i 1 e ( * 1 ' b ) 5 

read file (input_file) into (buff)i 
write file (output file) from (buff)! 



PAGE 



21 
22 



end 5 

end copy i 



Listing 10-5. Output from COPYLPT 
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This example shows that you can incorporate error handling in your programs to 
make them easier to use. In fact, you could enhance the COPYLPT program to handle 
errors in the first two input lines, or errors in the destination filename. 

To gain further experience, you could go back over all the previous examples and 
add ON-units to trap invalid input data and end-of-file conditions. Modifying these 
small programs gives you a good foundation in condition processing. 



End of Section 1 
References: Section 9 LRM 
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Section 1 1 
Character String Processing 



PL/I provides powerful character-string handling capabilities essential in a commer- 
cial production language. This section presents two sample programs that illustrate 
the use of some PL/I character-string functions. After you read the text and study the 
sample programs, you can make changes in the programs to expand your knowledge 
of PL/I. 



11.1 The OPTIMIST Program 

Our first example of string processing is a program called the OPTIMIST. The 
OPTIMIST program turns a negative sentence into a positive sentence. The OPTIMIST 
performs this task by using the character-string facilities of PL/I. 

Listing 11-1 shows the OPTIMIST program. The first segment, between lines 12 and 
23, defines the data items used in the program. The remaining portion reads a sentence 
from the console, ending with a period, and retypes the sentence in its positive form. 
Listing 11-2 shows a sample console interaction with the OPTIMIST. The OPTIMIST 
works well if sentences are simple, but complicated sentences confuse the program. 

Line 13 gives the OPTIMIST vocabulary of negative words, with the corresponding 
positive words on line 15. Thus, never becomes always, and none becomes all. OPTI- 
MIST replaces the word not with an empty string. Lines 17 through 20 declare the 
upper- and lower-case alphabets for case translation in the sentence processing section. 

OPTIMIST constructs each successive input sentence between lines 28 and 32, where 
the DO-group reads another word, and concatenates the word on the end of the 
sentence. The SUBSTR test in the DO WHILE heading checks for a period at the end. 

Note: OPTIMIST can only accept a sentence whose maximum length is 254 characters. 
PL/I discards any additional characters. 

After reading the complete sentence, OPTIMIST translates all upper-case characters 
to lower-case to scan the negative words. It performs this case translation on line 33 
by using the built-in TRANSLATE function. OPTIMIST uses the built-in VERIFY 
function on line 34 to ensure that the sentence consists only of letters and a period. 
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If the sentence consists of characters other than letters or a period, the VERIFY function 
returns the first nonzero position that does not match, and the OPTIMIST responds 
with: 

Actually* that's an interesting idea* 

If the VERIFY function returns a zero value, then the sentence contains only trans- 
lated lower-case letters and a period. In this case, control transfers to the DO-group 
between lines 36 and 42. On each iteration, OPTIMIST uses the built-in INDEX 
function to search for the next negative word, given by negative (i). If found, it sets j to 
the position of the negative word, and in the assignment statement on line 39, replaces it 
with the corresponding positive word. In this assignment, the portion of the sentence 
that occurs before the negative word is given by, 

s u b s t r ( s e n t » 1 * J - 1 ) 

while the replacement value for the negative word is given by, 

positiue(i) 

and the portion of the sentence that follows the negative word being replaced is given 
by: 

substr(sent»J+lendth(nedatiue(i))) 

The OPTIMIST concatenates these three segments to produce a new sentence with 
the negative word replaced by the positive word. It then sends the resulting sentence 
to the console, and loops back to read another input. Because all negative words have 
a leading blank, the negative portion is always found at the beginning of a word. Thus, 
OPTIMIST replaces nevermind with alwaysmind. This can produce interesting results. 

You could make at least three improvements to the OPTIMIST. First, if the sentence 
exceeds 254 characters, the input scan never stops, because the period is not found. 
You could include a check to ensure that the newly appended word does not exceed 
the maximum size. 

Second, there is no condition processing in the DO-group between lines 25 and 45, 
so the OPTIMIST never stops talking. It ends only through input of a CTRL-Z, end- 
of-file, or CTRL-C, system warm start. You could include an ON-unit to detect an 
end-of-file to end the program in a reasonable fashion. 

Finally, you could try to make the OPTIMIST smarter! 
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23 b 

24 b 
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2G c 

27 c 

28 d 

29 d 
30 
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3G 
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39 d 



40 
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41 


d 


42 


d 
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c 
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c 


45 


c 


46 


b 
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b 



/****#♦****** 
/* This p rosr 
/* processing 
/* positive o 
/****#*#**#*# 
optimist: 

procedure 
1 replace 
t rue 
false 
nwo rd 
declare 
neSat 
( 
posit 
( 
uppe r 
( 
1 owe r 
( 
sent 
word 
( i , J ) 



a****************************************-*/ 
am demonstrates PL/I character strinS */ 
by turning a negative sentence into a */ 
ne, */ 

♦ ♦♦♦♦a*********************-***************/ 

opt ions (main ) ! 

by v l 'b» 
by 'O'b t 
s by 5 i 

ive (l:nwords) character(B) uaryinS static initial 
x neijer' i 1 none' i 1 nothinS'** not'>' no') i 
ive (lrnwords) character(lO) varying static initial 
' always'*' all' » v something'*' v »' some')* 

cha racte r (28) static initial 
'ABCDEFGHIJKLMNOPQRSTUVHXYZ. ') t 

characte r(28) static initial 
v abcdefShiJKlmnopirstuuwxyz. ') > 
characte r (254) vary in St 
character(32) uaryinS* 

fixed! 



do while(true)! 

put skip 1 ist ( * What ' ' s up? ')! 
sent = v ' ! 
r— do while 

( subst r( sent tlenSth ( sent ) ) " = '.')! 
Set list ( wo rd ) i 
sent = sent ! ! v ' ! ! word! 
end 5 

sent = t ranslate ( sent t lowe r tuppe r) ! 
if uerify (sent dower) * = then 

sent = v that''is an interesting idea.'! 
i — do i = 1 to nwo rds ! 

J = index(sent»neSatiye(i))! 
if J "= then 

sent = subst r ( sent » 1 > j-l ) !! 
positiue(i) !! 

substr(sent >J+lenSth(ne*ative(i ) ) ) ! 
end ? 

put list( x Actuallyt'!!sent); 
put skip! 
— end ! 



end optimist ! 



Listing 11-1. The OPTIMIST Program 
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A>opti/wist 

What's up? Nothing is up, 
Actually* something is up. 

What's up? This is not fun, 
Actually* this is fun. 

What's up? Programs HRe this never make sense, 
Actually* programs liKe this always maKe sense. 

What's up? Nothing is easy that is not complicated , 
Actually* something' is easy that is complicated. 

What's up? Nobody cares and its none of your business, 
Actually* somebody cares and its all of your business. 

What's up? The price of everything, 
Actually* the price of everything'. 

What's up? Boy are ycru stupid, 
Actually* boy are you stupid. 

What's up? Dont get smart with me, 
Actually* dont Set smart with me. 

What's up? You started it I didnt, 
Actually* you started it i didnt. 

What's up? No I did not. 
Actually* some i did. 

What's up? Thats better, 
Actually* thats better. 

What's up? You are hard to talK to, 
Actually* you are hard to talk to. 

What's up? There you go again, 
Actually* there you g"o aSain. 

What's up? 77) ats it J quit. 
Actually* thats it i quit. 

Listing 11-2. Interaction with the OPTIMIST 
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What's up? Stop that. 
Actual ly t stop that . 

What's up? If you dont stop I will pull your pluf< 
Actually* if you dont stop i will pull your plus. 

What's up? You can not pull my plug* 
Actually* you can pull my plutfi 

What's up? I Know > 
Actually* i know . 

What's up? "Z 

END OF FILE (1). File: SYBIN=C0N 

TracebacK: 09C5 0970 0157 41 00 * 0909 0529 9090 0157 

A> 



Listing 11-2. (continued) 



11.2 A Parse Function 

This section presents a more practical application of string processing. It is often 
useful to have a separate subroutine in a program that reads a line of input and separates 
it into individual numbers and characters. Such a subroutine is called a parser, or a 
free-field scanner. The FSCAN program, shown in Listing 11-3, gives an example of 
a parser. 

FSCAN demonstrates the embedded subroutine called GNT, Get Next Token, which 
parses an input line into separate items called tokens. Once you test GNT, you can 
extract it from this program and put it into a production program where required. 
Section 13.4 uses GNT to compute values of arithmetic expressions. 

Listing 11-4 shows interaction with the FSCAN program. FSCAN reads a line of 
input, parses the line into separate tokens, and then writes the tokens back to the 
console, with surrounding apostrophes. The tokens are just numeric values, such as 
1234.56, or individual letters and special characters. GNT bypasses all intervening 
blanks between the tokens in the token scan. 

The FSCAN program has three parts. The first part, lines 10 to 12, defines the global 
data area called token, used by the GNT procedure. The second part, lines 14 to 42, 
is the GNT procedure itself. The third part is the DO-group between lines 44 and 47 
that performs the test of the GNT function procedure. 
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29 
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/♦ft************************************************/ 
/* This program tests the procedure called GNT > a */ 
/* free-field scanner (parser) that reads a line */ 
/* of input and breaks it into individual parts. */ 

f scan : 

procedure options (main ) 5 
Xreplace 

t rue by x 1 'b 5 
declare 

token characte r(80) uar/inS 

static init ial ( w ) 5 



*nt: 



procedure! 
declare 

i fixed i 

line characte r (80) uarvins 

static initial( w )5 

line = subst r( 1 ine »lenSth ( token ) + l ) ! 
r— do whi le ( t rue ) 5 

if line = w then 

Set edit(line) (a) 5 
i = ve rif y ( 1 ine » * ' ) 5 
if i = then 
line = w 5 
else 
t— do 5 

line = subst r( 1 ine >i ) 5 

i = uerify(line» % 012345G7B9. ') i 

— if i =0 then 
token = 1 ine 5 

— else 

— if i = 1 then 
token = subst r( 1 ine >1 >1 ) 5 

— else 
token = subst r( 1 ine »1 »i-l ) 5 

return? 
end 5 
L end i 
d ant » 



Listing 11-3. The FSCAN Program 
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44 c 




do whi le ( t rue ) ! 






45 c 




call an t ! 






46 c 




put ed i t ( * v x 


! ItoKen! ! ' ' 


') (x(l) >a> ; 


47 c 




end ! 






48 b 










49 b 


— end 


f scan ! 







Listing 11-3. (continued) 



(\>fscan 








88+9,3 








'88' v +' 


v 9,9' 




123 458 7 




89 


10 


* 1234567 




89. 


0' 


1 >2t3,li 


,5 


,8t7 




v l' * t ' 


2 


* > 


x 3 



M' ' ,"5' v ,' *G' ' ,' '7 



,,.,B66.,,, 7,7,7, 
X .,.,GGG.., , ' v 7.7,7, 



End of File (7). File: SYSIN=C0N 

Traceback: OBBE 27CA 0143 OOFF * 0B78 0986 0143 01F5 

A> 

Listing 11-4. Interaction with the FSCAN Program 

11.2.1 The GNT Procedure 

GNT stores the input line in the character variable called line that is initially empty 
due to the declaration on line 18. On the first call, GNT extracts the first portion of 
line and places it in token, which becomes the next input item. On each successive 
call, GNT removes the previous token value from the beginning of a line before scanning 
the next item. 

For example, suppose the input line is, 

^88*9.9 

where Jb represents a blank character. On the first call to GNT, both token and line 
are empty strings. The assignment on line 21 removes the previous value of token and 
leaves line as an empty string. The DO-group between lines 22 and 41 ensures that 
the line buffer is always filled. If GNT encounters an empty buffer, the GET EDIT 
statement, line 24, immediately refills it. The call to the built-in VERIFY function on 
line 25 returns the first position in line that is not blank. 
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If VERIFY returns a 0, then the entire line is blank and must be cleared. The refill 
operation takes place on the next iteration. If the line is not entirely blank, then control 
transfers to the DO-group beginning on line 29. 

11.2.2 The DO-Group 

Processing in the DO-group takes place as follows. On entry, the value of i is the 
first nonblank position of the line buffer. Thus, the statement on line 30 removes the 
preceding blanks from line, so the next token starts at the first position. GNT then 
calls the VERIFY function to determine if the next item in line is a number. 

The assignment statement on line 31 sets i to if the entire buffer consists of numbers 
and decimal points. Line 31 sets i to 1 if the first item is not a number or a period. It sets i 
to a larger value than 1 if the first item is a number that does not extend through the 
entire line buffer. Thus, this sequence of tests, starting at line 32, either extracts the entire 
line (i = 0), the first character of the line (i = 1), or the first portion of the line (i >1). 

In the preceding example input line, on the first iteration GNT sets line to, 

JK Jtf JK 8 8 * 9 . 9 

123456789 

where the index 1 through 9, in line, is shown below each character. On line 30, GNT 
removes the initial blanks, leaving line as: 



12 3 4 5 6 

Line 3 1 calls the VERIFY function that locates the first position containing a nondigit 
or period character. In this case, VERIFY returns the value 3, which corresponds to 
the * in position 3. As a result of the tests, FSCAN executes line 38 and produces the 
equivalent of: 

subst r< v 88*9 .9' »i ,2) 

This results in a token value of 88, which is the next number in line. 
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On the next call, GNT removes token from line using the SUBSTR operation on 
line 21 and leaves line as: 



The VERIFY function on line 31 returns the value 1, because the leading position 
of line is not a digit or a period. Line 36 extracts and returns the first character of line 
as the value of token. 

The third call to GNT gets the last token in line by first extracting the * . This leaves 
line as: 



This time, because all characters are either digits or periods, the VERIFY function 
returns a and GNT executes line 33. This results in a token value of 9.9, which is 
the remainder of line. 

The fourth call to GNT clears the previous value of token from line, so that line is 
the empty string. This causes GNT to execute the GET EDIT statement, line 24, and 
refill line from the console. Execution proceeds in this manner until you stop the 
program with a CTRL-Z or CTRL-C input. 

This simple parser has some obvious flaws. It does not trap end-of-file conditions. 
You could include an ON-unit to detect this condition, and return a null token value 
to indicate there' is no more input. Furthermore, GNT does not detect multiple period 
characters. This would cause a subsequent conversion signal (ERROR(l)) if you attempt 
to convert to a decimal value. 

These enhancements give you an improved version of GNT that you can incorporate 
into any of your programs. 

End of Section 1 1 

References: Sections 3.2, 6.4, 6.8 LRM 
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Section 12 
List Processing 



For some programs it is difficult to determine the exact memory requirements before 
the program runs. List processing is an example of this kind of program because the 
number of data elements can vary considerably while the program is running. 

PL/I has subroutines in the Run-time Subroutine Library (RSL) that dynamically 
manage storage allocation. When the operating system loads a PL/I program into the 
Transient Program Area (TPA) or partition, PL/I first initializes all the remaining free 
memory as a linked list. The list elements contain information fields and pointers to 
other list elements. A program dynamically allocates memory by using the ALLOCATE 
statement and releases memory using the FREE statement. PL/I continuously keeps all 
memory segments connected to one another by using the linked-list mechanism. 

The programs in this section illustrate list processing in two cases where it is not 
easy to predetermine the amount of storage required. 



12.1 Based and Pointer Variables 

You can visualize a based variable as a template that fits over a region of memory 
but has no storage directly allocated to it. A pointer variable is just a two-byte value 
that holds the address of a variable. When you use a pointer variable, you are pro- 
grammatically placing this based variable template over a particular piece of memory. 
The method depends on the form of the based variable declaration. 

If the based variable declaration does not include an implied base, then you must 
qualify any reference to the based variable with a pointer. If the based variable dec- 
laration includes an implied base, then you can include a pointer qualifier in any 
reference to the based variable, or you can simply use the implied pointer given in the 
declaration as a base. 
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Consider the following example declaration: 

declare 
i fixed > 
mat (0:5) fixed > 
(pi q) pointer* 
x fixed based » 
y fixed based(p) t 
z fixed based(f())5 

PL/I allocates storage for the two variables i and mat because they are not based 
variables. PL/I also assigns storage locations for the two pointer variables p and q. 
However, the three variables x, y, and z are declared as based variables, and they have 
no storage locations prior to execution. Instead, PL/I determines their actual storage 
addresses as the program runs. The variable x has no implied base, so every reference 
to x must have a pointer qualifier such as: 

p - > x = 5 5 
or, 

s - > x = s ; 

The first statement assigns the value 5 to the fixed two-byte variable at the memory 
location given by p. The second statement assigns the value 6 to the location given by 

q- 

The variable y, on the other hand, has an implied base that means you can reference 
it with or without a pointer qualifier. The reference 

y = 55 

equals 

p - > y - 5 5 

and thus, 

v = 5 5 and q - > y = Si 
have exactly the same effect as the two preceding assignments to x. 
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The variable z, like the variable y, has an implied base. In this case, the base is an 
invocation of a pointer-valued function with no arguments. For example, the function 
f can take the form: 

f : 

procedure retums(pointer) 5 

return ( a d d r ( m a t ( i ) ) ) 5 
e n d f 5 

Using this definition of f, you can reference z as: 

p - > z = 5 ; 

or, 

2 = g; 

The first form is equivalent to those shown above, with the location derived from the 
pointer variable p. The second form however, is an abbreviation for: 

f ( ) - > z = G 5 

In this case, PL/I evaluates the function f to produce the storage address for the based 
variable z. This form has a twofold advantage. First, the pointer-valued expression can 
be complex, and not restricted to a simple pointer variable. Second, the code for function 
f appears only once, rather than being duplicated at each variable reference. This can 
save a considerable amount of space in a program. 

Note: the implied base must be in the scope of the declaration for the based variable. 
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The following incorrect code sequence illustrates this concept: 

main: 

procedure optioris(wain) ! 
declare 

x based ( p ) * 
y b a s e d ( q ) * 
p pointer? 
r- b e i n 5 

declare 

( p m) pointer? 
x = 55 
y = 10 5 
end 5 
declare 

q pointer! 
u end wain? 

Because the variables x and y are based on p and q, the pointers p and q must be 
in the same or encompassing scope. Here the pointers p and q are declared in the 
embedded BEGIN block that is a different environment. 



12.2 The REVERSE Program 

Our first example of list processing is a program called REVERSE. The OPTIMIST 
program in Section 1 1 can accept a sentence with a maximum of 254 characters, the 
maximum string length. REVERSE, however, accepts sentences of virtually any length 
by using a list structure instead of a single character string. Instead of performing word 
substitution, REVERSE simply reverses the input sentence. 

Listing 12-1 shows the REVERSE program, which is divided into three parts. The 
first part, lines 12 through 17, reads a sentence from the console and writes the sentence 
back to the console in reverse order. Each input sentence consists of a sequence of 
words up to 35 characters in length. This is sufficient to hold, 

supercalifragilisticexpialidocious 

one of the longest words in the English language. 

To simplify the input processing, REVERSE requires a space before the period that 
ends the sentence. REVERSE also ends execution when you type an empty sentence. 
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The second part of REVERSE is a separate subroutine, called read_- it, which starts on 
line 19. The third part is a subroutine called write_it, which begins on line 37. Making 
these functions separate subroutines in the main program simplifies the overall structure. 

Listing 12-2 shows the console interaction with REVERSE. 
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/* This program reads a sentence and reverses it. */ 
/ft*************************************************/ 
reve rse : 

procedure opt i ons (main ) ! 
declare 

sentence pointer* 
1 wordnode based (sentence)* 
2 word characte r(35) uaryinS* 
2 next pointer! 



do whi le ( M 'b ) 5 

call read_it ( ) 5 

if sentence = null then 
stop 5 

call w ri t e_i t ( ) 5 
end i 

read_it : 

procedure ! 
declare 

newword characte r (35) uaryina't 
newnode pointer! 
sentence = null! 
put skip list ( 'What ' 's up? ')! 
do wh i le ( M ' b ) ! 

Set list (newwo rd ) ! 
if newwo rd = x . ' then 

return ! 
allocate wordnode set (newnode)i 
newnode->next = sentence! 
sentence = newnode ! 
wo rd = newwo rd ! 

end ! 
end read i t ! 



Listing 12-1. The REVERSE Program 
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37 


b 




- write it : 


38 


c 




procedure i 


39 


c 




declare 


40 


c 




p pointer! 


41 


c 




put skip 1 ist ( 'Actual ly » ')! 


42 


d 






i— do while (sentence "= null)! 


43 


d 






put 1 ist (wo rd ) ! 


44 


d 






p = sentence ! 


45 


d 






sentence = next ! 


46 


d 






free p->wo rdnode 5 


47 


d 






*— end ! 


48 


c 




put 1 ist ( ' . ' ) ! 


49 


c 




put skip? 


50 


c 




— end write it! 


51 


b 




52 


b 


- er 


id reye rse ! 



Listing 12-1. (continued) 



&>reverse 

What's up? North is up , 

Actual lv » up is North ♦ 

What's up? The rain in Spain falls mainly in the plain , 

Actually* plain the in mainly falls Spain in rain The . 

What 's up? 3 + 5 = 8, 

Actually » 8 = 5 + 3, 

What's up? , 

A> 

Listing 12-2. Interaction with the REVERSE Program 

The REVERSE program stores each word in a separate area of memory, obtained 
using the ALLOCATE statement on line 30. On each iteration of the DO-group, the 
ALLOCATE statement obtains a unique section of the free memory space sufficiently 
large to hold the wordnode structure defined on line 8. The wordnode elements are 
linked together through the next field of each allocation, and the beginning of the list 
is given by the value of the sentence pointer variable. 
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Each allocation consumes 38 bytes. You can verify this by examining the Symbol 
Table. The wordnode structure is 38 bytes long because word is declared as CHAR- 
ACTER^) VARYING, and requires one byte to hold the current length, 35 bytes to 
hold the string itself, and is followed by a two-byte pointer value. 

For example, given the input sentence, 

I SHALL RETURN . 

REVERSE executes the ALLOCATE statement three times, once for each word in the 
list. 

Suppose that these three memory allocations are found at addresses 1000, 2000, 
and 3000. The REVERSE program begins by reading the sentence in the main DO- 
group in the read_it procedure. It initializes the sentence pointer to the null address 
(0000) . Upon entering the DO-group at line 26, the value of sentence appears as follows : 

SENTENCE: 0000 

REVERSE reads the first word with the GET statement on line 27, and because the 
value is not a period, it allocates the first 3 8 -byte area to hold the word. As it constructs 
the sentence, REVERSE places the pointer value of the sentence variable into the next 
field, and the input word into the word field. The most recently read word then becomes 
the new head of the list. After processing the word I, the list appears as shown below: 

SENTENCE: 1000 



1000: 



0000 



REVERSE then proceeds through the loop again. This time, it reads the word SHALL 
and allocates the second 3 8 -byte area. The newly allocated area becomes the new head 
of the list, with the resulting pointer structure: 



SENTENCE 



2000 



2000: 



SHALL 



1000: 



1000 



0000 
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REVERSE repeats the loop once again and processes the last word, RETURN, and 
allocates the final 3 8 -byte area, placing it at the head of the list that results in the 
following sequence of nodes: 



SENTENCE: 



3000 



3000: 



RETURN 



2000 



2000: 



SHALL 



1000 



1000: 



0000 



The program follows the pointer structure from the sentence variable to the node for 
RETURN, then to the node for SHALL, and finally to the node for I, where it encounters 
an end-of-list value 0000. 

REVERSE actually builds the list in reverse order. The DO-group in the write_it 
procedure, lines 42 to 47, simply searches through the list, starting at the sentence 
pointer, and prints each word it encounters. As soon as the word is written, the FREE 
statement on line 46 releases the 38-byte area allocated to it. The write_it procedure 
moves the sentence pointer variable to the next item in the list before it executes the 
FREE statement to free the current element. 

Note: storage does not remain intact after it is released. 

The advantage of the list structure is that the sentence can be arbitrarily long, limited 
only by the size of available memory. The disadvantage, of course, is that there is 
considerably more storage consumed for sentences that could be represented by a 254- 
character string. 



12.3 A Network Analysis Program 

The next example is extensive and illustrates two points. First, it demonstrates the 
power of PL/I list-handling constructs. Second, it shows how to divide a large, complex 
program into small, logically distinct units, and thereby simplify the coding task. 

The NETWORK program shown in Listing 12-4 performs a network analysis. That 
is, it finds the shortest path between nodes in a network. The user enters a network 
of cities and distances between the cities. Then NETWORK constructs a connected set 
of nodes using list processing structures. Upon demand from the user, NETWORK 
computes the shortest path from all cities in the network to the assigned destination, 
and then selectively displays particular optimal paths through the network. 
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It is easier to understand how the program operates if you first examine the console 
interaction shown in Listing 12-3. First, you enter a list of cities and distances between 
the cities, ending the entry with a CTRL-Z. Entering a CTRL-Z triggers a display of 
the entire network to aid in detection of input errors. NETWORK then prompts you 
for a destination city, in this case, Tijuana, and a starting city, in this case, Boise. 

NETWORK then displays a best route. There can be several of equal length. Next, 
NETWORK prompts for another starting city. If you enter a CTRL-Z, NETWORK 
reverts to another destination prompt, leaving the network intact. Interaction continues 
in this manner until you enter a CTRL-Z in response to the destination prompt. When 
this occurs, NETWORK clears the network and returns to accept an entirely new 
network of cities and distances. The entire program ends if you enter an empty network 
at this point, for example, a CTRL-Z. 

9\>netuo rK 

Type "Ci t y 1 >Dist » Citv2" 
Seattle, 150, Boise 
Boise, 300, Modesto 
Seattle, 400, Modesto 
Modesto, 150, Monterey 
Modesto, 50, San-Francisco 
San-Francisco , 200, Las-Vegas 
Las-Vegas , 350, Monterey 
Los-Angeles , 400, Las-Vegas 
Bakersfield , 300, Monterey 
BaKersfield , 250, Las-Vegas 
Los-Angeles , 450, TiJuana 
TiJuana, 700, Las-Vegas 
Las-Vegas , 920 > Boise 
Pacific-Grove , 5, Monterey 



Pacif ic-G roue : 

5 miles to Monte rey 
TiJuana : 

700 miles to Las-VeSas 

450 miles to Los-Angeles 
BaKersfield : 

250 miles to Las-Vesfas 

300 miles to Monterey 
Los-AnSeles : 

450 miles to TiJuana 

400 miles to Las-UeSas 

Listing 12-3. Interaction with the NETWORK Program 
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Las-VeSas : 

920 mi 

700 mi 

250 mi 

400 mi 

350 mi 

200 mi 

San-Francisc 

200 mi 

50 mi 

Monterey : 

5 mi 

300 mi 

350 mi 

150 mi 

Modesto : 

50 mi 

150 mi 

400 mi 

300 mi 

Boise : 

920 mi 

300 mi 

150 mi 

Seattle : 

400 mi 

150 mi 



es to Boise 

es to Tijuana 

es to Bakersfield 

es to Los-AnSeles 

es to Monte rey 

es to San-Francisco 

es to Las-VeSas 

es to Modesto 

es to Pacific-Grove 

es to Bakersfield 

es to Las-UeSas 

es to Modesto 

es to San-F ranci sco 

es to Monterey 

es to Seattle 

es to Boise 

es to Las-VeSas 

es to Modesto 

es to Seattle 

es to Modesto 

es to Boise 



Type Destination TiJuana 



Type Start Boise 



1250 miles remain » 

950 miles remain t 

900 miles remain > 

700 miles remain » 

Type Start '"Z 



300 miles to Modesto 

50 miles to San-Francisco 

200 miles to Las-UeSas 

700 miles to TiJuana 



Listing 12-3. (continued) 
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Type Destination Pacific-Grove 

Type Start Seattle 

555 mi les remain t 

155 miles remain t 

5 miles remain > 
Type Start "2 

Type Destination "Z 

Type " C i t y 1 > D i s t » City2" 

A> 



400 miles to Modesto 
150 miles to Monte rey 

5 miles to Pac i f i c-Grove 



Listing 12-3. (continued) 

12.3.1 NETWORK List Structures 

NETWORK uses two data structures as list elements. The first structure is called a 
citynode and corresponds to a particular city. It is defined on line 16 of Listing 12- 
4. The city_node structure is shown below: 



CITY NODE: 



city_name 



total distance 



investigate 



citylist 



route head 



The city_name field holds the character-string value of the city's name, while the 
total_distance and investigate fields are used by the shortest_distance procedure. The 
city_list and route_head pointer values link together all the cities in the network. 

The second structure is called a route_node, and is defined on line 23. A route_node 
establishes a single connection between a city and one of its neighbors. You allocate 
several route_nodes for a city, corresponding to the number of connections to its 
neighboring cities. The route_node structure is shown below: 



ROUTE NODE: 



next_city 



route_distance 
route list 
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The list of route_nodes associated with a particular city begins at the pointer value 
called routejhead that is a part of the city_node structure. The route is determined by 
following the route_list pointer to additional route_nodes, until you encounter a rou- 
te_node with a null entry in the route_list. Each route_node also has a pointer value, 
denoted by next_city, that leads to a neighboring city_node, along with a route_dist- 
ance field that gives the mileage to the next city. 

The following example illustrates this concept. Assume Monterey is 350 miles from 
Las Vegas. NETWORK must allocate two city_nodes and two route_nodes with sample 
addresses to the left of each allocation as follows. You can temporarily ignore the fields 
marked x in the diagram. 



CITY NODE 



CITY NODE 



1000 



Monterey 



xxxxxxx 



xxxxxxx 



xxxxxxx 



3000 



2000 



Las Vegas 



xxxxxxx 



xxxxxxx 



xxxxxxx 



4000 



ROUTE NODE 



ROUTE NODE 



3000 



2000 



4000 



1000 



350 



350 
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A linked list, starting at city_head, leads to all cities in the network. Given the 
preceding two cities, the list of cities appears as follows: 

CITY HEAD 



1000 



CITY NODE 



CITY NODE 



1000 



Monterey 



xxxxxxx 



xxxxxxx 



2000 



xxxxxxx 



2000 



Las Vegas 



xxxxxxx 



xxxxxxx 



0000 



xxxxxxx 



12.3.2 Traversing the Linked Lists 

Several of the procedures in NETWORK use one particular form of an iterative DO- 
group to traverse the linked lists. The statement on line 95 is typical: 

do p = city_head repeat ( p- >c i t y_l i s t ) while ( p" =rnil 1 ) 5 

The DO-group header successively processes each element of the linked list starting at 
city_head until it encounters a null link, 0000. On the first iteration, the DO-group 
sets the pointer variable p to the value of the pointer variable cityhead. In the example 
above, this results in the assignment p = 1000. 

On the next iteration, p takes on the value of the city_list field at 1000 that addresses 
Las Vegas. This results in the value p = 2000. On the last iteration, p takes on the 
value of the city_list field based at 2000, resulting in p = 0000. The DO-group then 
stops executing because p is equal to null. 
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12.3.3 Overall Program Structure 

Keeping in mind the preceding discussion, look at the overall program structure. 
The top-level program calls occur in the DO-group between lines 31 and 38. The 
remainder of the program consists entirely of the nested subroutines described below. 

NETWORK is logically divided into four parts: 

■ The input section constructs and echoes the network of cities, consisting of four 
procedures beginning on line 45: setup, connect, find, and print_all. 

■ The analysis of the shortest path between the cities takes place in the 
shortest_distance procedure starting on line 164. 

■ The shortest path display operations are split between the two procedures 
print_paths and print_route, respectively. 

■ The free_all procedure clears the old network before loading a new network. 

Beginning on line 32, the main program calls setup to read the network. If the 
city_list is empty, then NETWORK stops. Otherwise, it calls print_all to display the 
network, and then calls print_paths to prompt and display the shortest routes. Upon 
return, NETWORK calls free_all to release storage. This process continues until you 
enter an empty network. 

12.3.4 The Setup Procedure 

The main loop in setup occurs between lines 54 and 58. On each iteration, the GET 
LIST statement, line 55, reads a pair of cities with a connecting distance. Next, setup 
calls the connect subroutine twice to establish the connection in both directions between 
the cities. The ON-unit on line 50 intercepts the CTRL-Z. 

12.3.5 The Connect Procedure 

The connect procedure establishes a single route_node to connect the first city to 
the second city. The connect procedure does this by calling the find procedure twice, 
once for the first city and once for the second city. The find procedure locates a city 
if it exists in the network, or creates the city_node if it does not yet exist. Upon return 
from find, the connect procedure creates and fills in the route_node, lines 79 to 82. 
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In the previous example, the first call to connect establishes the city_nodes for 
Monterey and Las Vegas, indirectly through the find procedure, and then produces the 
routenode under Monterey only. The second call to connect establishes the route_node 
under Las Vegas. 

12.3.6 The Find Procedure 

The find procedure, starting at line 89, searches the city_list, beginning at city_head, 
until it finds the input city or exhausts the city_list. If the input city does not exist, 
find creates it between lines 100 and 105. In any case, find returns a pointer to the 
requested cityjnode. 

12.3.7 The Print_AH Procedure 

The print_all procedure appears between lines 113 and 127. NETWORK calls 
print_all after creating the network. This procedure starts at city_head and displays 
all the cities in the city_list. As it visits each city, print_all also traverses and dis- 
plays the route_head. Upon completion of the print_all procedure, all city_nodes and 
route_nodes have been visited and displayed. 

12.3.8 The Print_Paths Procedure 

The print_paths procedure reads a destination city on line 143 and sends it to the 
shortest_distance procedure. Upon return, print_paths sets the total_distance field of 
each city_node to the total distance from the destination city. You enter the starting 
city on line 148, and print_paths sends it to the print_route procedure for the display 
operation. 

12.3.9 The Print_Route Procedure 

The print_route procedure at line 214 displays the best route from the input city to 
the destination. The procedure finds the best route as follows: The total distance from 
the input city to the destination has already been computed and stored in the 
total_distance field. The procedure obtains the first leg of the best route by finding a 
neighboring city whose total_distance field differs by exactly the distance to the neigh- 
bor. It then displays the neighbor, moves to the neighboring city, and repeats the same 
operation. Eventually, it reaches the destination city and completes the display operation. 

Line 221 finds the original city_node. Line 231 displays the remaining distance, and 
the search for the first or next leg occurs between lines 233 and 244. On each iteration, 
line 236 tests to determine if a neighbor has been found whose total distance plus the 
leg distance matches the current city. If so, line 238 displays the leg distance and the 
search terminates by setting q to null. 



143 



12.3 A Network Analysis Program PL/I Programming Guide 



12.3.10 The Shortest_Distance Procedure 

This procedure takes an input city, called the destination, and computes the minimum 
total distance from every city in the network to the destination. It then records this 
total at each city_node in the total_distance field. In calculating the minimum total 
distance, the procedure implements the following algorithm: 

1. Initially mark all total_distance fields with infinity, 32767 in PL/I, to indicate 
that the node currently has no connection. 

2. Set the investigate flag to false for each city. The investigate flag marks a 
city_node that needs further processing. 

3. Set the total_distance to the destination at zero; all others are currently set 
to infinity, but change during processing. 

4. Set the investigate flag to true for the destination only. 

5. Examine the city_list for the city_node that has the least total_distance, and 
whose investigate flag is true. At first, only the destination is found. When no 
city_node has a true investigate flag, all processing is complete and all min- 
imum total_distance fields have been computed. 

6. Clear the investigate flag for the city found in 4, and extract the current value 
of its total_distance field. Examine each of its neighbors; if the current 
total_distance field plus the leg distance is less than the total_distance field 
marked at the neighbor, then replace the neighbor's total_distance field by 
this sum. Then mark the neighbor for processing by setting its investigate flag 
to true. After processing each neighbor, return to step 4. 

The algorithm thus proceeds through the network, developing the shortest path to 
any node, and as a result, visiting each city exactly once. This is because the process 
is linear, and any additional nodes do not significantly effect the time to analyze the 
network. 

12.3.11 The FreeAU Procedure 

The final procedure, free_all starting at line 251, returns the network storage at the 
end of processing each network. The procedure visits and then discards each city_node 
and the entire list of route node connections. 
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12.3.12 NETWORK Expansion 

You can expand NETWORK in several ways. First, you can open a STREAM file 
and read the graph from disk, because it is inconvenient to type an entire network 
each time you run the program. You can also store several networks on disk and 
retrieve them on command from the console. 



l 

2 
3 

5 

G 

7 

8 

9 

10 

11 

12 

13 

in 

15 
1G 
17 
18 
19 
20 
21 
22 
23 

ia 

25 
26 
27 
28 
29 
30 
31 
32 
33 

3a 

35 
36 
37 
38 
39 



/***** 
/* Thi 
/* in 
/* 8ET 
/* SHO 
/***** 
netwo r 
p r 
Xr 



de 



de 



*********** 
s program f 
a netwo rK . 
UP* CONNECT 
RTEST_DISTA 
*********** 
k: 

ocedu re opt 
epl ace 
t rue 
false 
c i t y s ize 
infinite 
clare 

s v s i n f i 1 
clare 

1 c i t y_n o 
2 city_ 
2 total 
2 i n y e s 
2 city_ 
2 route 
clare 

1 route_n 

2 next_ 

2 route 

2 route 

clare 

city head 



************#*****##**************#***/ 
inds the shortest path between nodes */ 
It has 8 internal procedures: */ 
» FIND* PRINT..ALL. PRINT_PATHS* */ 
NCE* PRINT_R0UTE» and FREE_ALL. */ 
*#**************************#*****#***/ 

i ons ( Main ) 5 

by M 'b . 

by v ' b » 

by 20. 

by 32767! 



de based t 

name cha rac t e r ( c i ty s i ze ) varyin? 

_distance fixed » 

t i 3at e bit* 

list pointer* 

_head pointer! 

ode based * 
city pointer* 
_distance fixed* 
_list pointer! 

pointer! 



do whi le ( t rue ) ! 

call setup () ! 

if city_head = null then 
s top ; 

call p rint_al 1 ( ) i 

call p rint_paths ( ) ! 

call f ree_all ( ) 5 
end ! 
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40 


b 


41 


b 


42 


b 


43 


b 


44 


b 


45 


b 


46 


c 


47 


c 


48 


c 


49 


c 


50 


c 


51 


c 


52 


c 


53 


c 


54 


d 


55 


d 


56 


d 


57 


d 


58 


d 


59 


c 


60 


c 


61 


b 


62 


b 


63 


b 


64 


b 


65 


b 


66 


b 


67 


b 


68 


b 


69 


c 


70 


c 


71 


c 


72 


c 


73 


c 


74 


c 


75 


c 


76 


c 


77 


c 


78 


c 


79 


c 


80. 


c 


81 


c 


82 


c 


83 


c 


84 


b 



/* This procedure reads two cities and then calls the */ 
/* procedure CONNECT to establish the connection (in */ 
/* both directions) between the cities. */ 

/♦♦♦a**************************************************/ 
i — setup : 

procedure ! 
declare 

distance fixed* 

(cityl* citx2) characte r ( c i ty si ze ) varying! 
on endf i le ( sxsin ) Soto eofi 
ci ty_head = null! 

put skip listPType "Cityl* Distt C i t y 2 ! " ' ) ! 
put skip! 
i — do whi le ( t rue ) 5 

Set listtcitylt distance* city2)i 
call connect ( city 1 » distance* city2)5 
call connect ( city2 * distance* cityl)! 
end ! 
eof : 
— end setup? 

/ft*****************************************************/ 
/* This procedure establishes a sinsfle route_node to */ 
/* connect the first city to the second city by */ 
/* calling the FIND procedure twice! once for the */ 
/* first city and once for the second city. */ 

/###**#**#**#**##******♦**************♦*#*##******##***/ 
-connect: 

procedu re ( 5ource_ci ty * distance* des t inat ion_c i t y ) ! 
declare 

source_city characte r( ci tysize ) varying* 
dest inat ion_ci ty characte r ( c i tys i ze ) varying* 
distance fixed* 
( r > s* d) pointer! 

s = f ind ( source_ci ty ) ! 
d = f ind ( destination_city ) ! 
allocate route_node set (r)! 
r->route_distance = distance! 
r->next_city = d 5 
r->route_l ist = s->route_head ! 
s- > route_head = ri 
-end connect! 



Listing 12-4. (continued) 
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85 


b 


8G 


b 


87 


b 


88 


b 


89 


b 


90 


c 


91 


c 


92 


c 


93 


c 


94 


c 


95 


d 


9B 


d 


97 


d 


98 


d 


99 


d 


100 


c 


101 


c 


102 


c 


103 


c 


104 


c 


105 


c 


106 


c 


107 


c 


108 


b 


109 


b 


110 


b 


111 


b 


112 


b 


113 


b 


114 


c 


115 


c 


116 


c 


117 


c 


118 


d 


119 


d 


120 


d 


121 


e 


122 


e 


123 


e 


124 


B 


125 


e 


126 


d 


127 


c 


128 


b 



/♦♦a***********************************************/ 
/* This procedure searches the list of cities and */ 
/* returns a pointer to the requested city_node. */ 

-find: 

procedure(city) returns(pointer) ! 
declare 

city cha ract e r ( c i tys i ze ) varying* 
(p> q ) pointer! 

-do p = city_head 

repeat(p->city_list) while(p A =null) ! 
if city = p->ci ty_name then 
return ( p) ! 
-end ! 

allocate city_node set(p)i 
p->ci ty_name = city 5 
p->city_list = city_headi 
ci ty_head = p i 
p- >total_d i stance = infinite! 
p- > route_head = null! 
return ( p) 5 
-end find 5 

/* This procedure starts at the city_head and */ 
/* displays all the cities in the city_list. */ 

-prin t_al 1 : 

procedure ! 
declare 

( p » q ) pointer! 

do p = city head 

repeat(p->city_list) while(p"=null) ! 
put sKip 1 ist ( p->city_name > ' : ' ) ! 
•do q = p- > route_head 

repeat(q->route_list) while(q"=null) ! 
put skip 1 i st ( q- >route_d istance > * mi 1 es to ' » 
q->next_city->ci ty_name ) ! 
-end ! 
-end ! 
-end print all! 



Listing 12-4. (continued) 



147 



PL/I Programming Guide 



12.3 A Network Analysis Program 



129 


b 


130 


b 


131 


b 


132 


b 


133 


b 


134 


b 


135 


b 


13G 


c 


137 


c 


138 


c 


139 


c 


140 


c 


141 


d 


142 


d 


143 


d 


144 


d 


145 


d 


146 


e 


147 


e 


148 


8 


149 


e 


150 


e 


151 


d 


152 


d 


153 


c 


154 


c 


155 


b 



/**********#***##**#**##****#**##***♦**#*##*#****#*#***/ 
/* This procedure reads a destination city* calls the */ 
/* SHORTEST-DISTANCE procedure) and sets the */ 

/* total-distance field in each city_node to the */ 
/* total distance froin the destination city. */ 

/****#*****#*#■:•:#**#********#**#**##*****#*******#*###**/ 
-print_paths : 

procedure i 

declare 

city characte r ( ci tysize ) varying? 

on endf i le ( sy s in ) Soto eofi 
-do while(true); 

put sKip list('Type Destination ')5 
Set list(city)! 
call sho rt est_distance ( c i ty ) ! 
on endf i le ( sysin ) Soto eol! 
-do while(true)! 

put sKip list( v Type Start ')! 
Set list(city); 
call print__route(city)5 
—end 5 
eol: reuert endfile(sysin)? 
-end 5 
eof : 
-end print paths? 



Listing 12-4. (continued) 
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156 


b 


/***#****# 


157 


b 


/* This pr 


158 


b 


/* taKes a 


159 


b 


/* the win 


1B0 


b 


/* netwo rK 


161 


b 


/* Minimum 


162 


b 


/* c i t y_no 


163 


b 


/#******** 


164 


b 




— sho rt e 


165 


c 




p r 


166 


c 




de 


167 


c 






168 


c 




de 


169 


c 






170 


c 






171 


c 






172 


d 






, — do 


173 


d 








174 


d 








175 


d 








176 


d 






— en 


177 


c 




p 


178 


c 




p- 


179 


c 




p- 


180 


d 






1 do 


181 


d 








182 


d 








183 


e 










184 


e 










185 


e 










186 


f 










187 


f 










188 


4 










189 


S 










190 


4 










191 


4 










192 


f 










193 


e 










194 


d 








135 


d 








196 


d 











**********#**♦###*#** 
ocedure is the heart 
n input city* the des 
imum total distance f 

to the destination. 

value in the total_d 
de. 

st_d i s t ance : 
ocedure (city) 5 
c 1 a re 

city cha rac te r ( c i ty 
c 1 a re 

bestp pointer* 
(d 1 bestd) fixed > 
(pi q * r) pointer! 
p = city_head 
repeat ( p- >ci ty_l i st ) 
p- >to tal_d ist ance = 
p- >in ves t i Sate = f al 
di 

= find(city)! 
>to t al_d i st ance = ! 
> investigate = true! 
wh i 1 e ( t rue ) ! 
bestp = null! 
bestd = infinite! 
-do p = city_head 

repeat ( p- >c i t y_l i 
if p->invest i Sate 
do 1 

if p->total_ 
1 — do ! 

bestd = 
bestp = 
— end ! 
end ! 
end 5 
if bestp = null then 

ret u rn ! 
bestp-> investigate = 



of the p rogram. It */ 
tination* and computes */ 
roM every city in the */ 
It then records this * / 
istance field of every */ 
*/ 
**##***♦*#***#*#***#*#**/ 



size) varying! 



w h i 1 e ( p * = n u 1 1 ) ! 
infinite! 
se ! 



st) while(p"' = null)i 
then 



distance < bestd then 
p->total distance ! 



false ! 



Listing 12-4. (continued) 
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197 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 

208 c 

209 b 

210 b 

211 b 

212 b 

213 b 

214 b 

215 c 
21G c 

217 c 

218 c 

219 c 

220 c 

221 c 

222 d 

223 d 

224 d 

225 e 
22G e 
227 e 
228 
229 
230 
231 
232 



-do <i = bestp->route_head 

repeat(q->route_list) while(q A =null) 5 

r = q->next_c i ty 5 

d = bestd + 9- > rout e_di stance 5 

if d < r->total_distance then 

i — do i 

r->total_d i stance = d? 
r - > i n v estimate = true! 
-end ? 



-end i 
end ! 

I — end shortest distance? 



/**#*#*****#***#***#*#*******#*##*##*#*♦**♦#****/ 
/* This procedure displays the best route from */ 
/* the input city to the destination. */ 

/*##***#**♦****#**#*#*##**###******###*#***#****/ 
-print_ route: 

procedure (city) 5 
declare 

city characte r (ci tysize ) varying! 
declare 

( p m ) pointer* 
( t »d) fixed i 
p = find(city)! 
-do whi le ( t rue ) ! 

t = p- >total_distance ! 
if t = inf inite then 
-do ; 

put skip list( v (No Connection)')! 
return 5 
-end! 
if t = then 

re tu rn ! 
put skip listtt Smiles remain*')! 
q = p->route head i 



Listing 12-4. (continued) 
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233 e 








1 — do while(q"=null)i 


234 e 








p = q->next city! 


235 e 








d = q- > route distance! 


23G e 








if t = d + p->total distance then 


237 f 










— do ! 


238 f 










put list ( d » 4 mi les to'»p->city name)! 


239 f 










q = null! 


2ao f 










— end i 


241 e 








else 


242 e 








q = q - > route list! 


243 e 








end ! 


244 d 






1 end 5 


245 c 




— e nd print_ route! 


246 b 




247 b 


/♦♦♦a**********************************************/ 


248 b 


/* This procedure frees all the storage allocated */ 


249 b 


/ * by the program while processing the network. */ 


250 b 


/♦a************************************************/ 


251 b 




— free_all: 


252 c 




procedure » 


253 c 




declare 


254 c 




(p» q ) pointer? 


255 d 






1 do p = city head 


25G d 






repeat ( p->c ity list) wh i 1 e ( p" =nul 1 ) 5 


257 e 








— do q = p - > route head 


258 e 








repeat(q->route list) while(q"=null)5 


259 e 








free q- > route node! 


260 e 








1 — end ! 


2G1 d 






free p->city node! 


262 d 






end 5 


263 c 




— end free all! 


264 b 




265 b 


en 


d n 


etwc 


irk ! 





Listing 12-4. (continued) 

End of Section 12 
References: Sections 3.4, 7.1-7.8, 8.2 LRM 
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Section 13 
Recursive Processing 



Recursive processing occurs when an active procedure calls itself, or is called by 
another active procedure. There are many programming problems that lend themselves 
to this kind of construct. This section has three such problems. The first two illustrate 
the basic concepts, and the last one uses recursion in a practical problem. 

In a recursive procedure, a CALL statement, or function reference contained in the 
procedure itself, reinvokes the procedure before returning to the first level call. There- 
fore, you must declare all such procedures with the RECURSIVE attribute so PL/I can 
properly save and restore the local data areas at each level of recursive call. 

PL/I places two restrictions on RECURSIVE procedures. First, it passes all procedure 
parameters by value. You cannot return values from a recursive procedure by assign- 
ment to formal parameters. Instead, you can return a functional value or assign values 
to global variables. 

Note: to maintain compatibility with full PL/I, you should not use formal parameters 
on the left of an assignment statement in a PL/I RECURSIVE procedure. 

Second, PL/I does not allow BEGIN blocks in RECURSIVE procedures. However, 
it does allow nested procedures and DO-groups. The examples that follow illustrate 
the proper formulation of RECURSIVE procedures. 



13.1 The Factorial Function 

The classic example of recursion is evaluation of the Factorial function. This function, 
used throughout mathematics, is a good illustration because you can define it by 
iteration and recursion. 

The iterative definition of the Factorial function is 

n! = (n)(n-l)(n-2) ... (2)(1) 



M 
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where n! is the Factorial function, and n is a nonnegative integer. Therefore: 

(n-1)! = (n-l)(n-2) ... (2)(1) 
You can define the Factorial function using the recursive relation: 

n! = n(n-l)! (by definition, 0! = 1) 

Evaluating the Factorial function using either iteration or recursion produces the 
following values: 

0! = 1 
1! = 1 

2! = (2) (1) = 2 
3! = (3) (2) (1) = 6 
4! = (4) (3) (2) (1) = 24 
5! = (5) (4) (3) (2) (1) = 120 
6! = (6) (5) (4) (3) (2) (1) = 720 
7! = (7) (6) (5) (4) (3) (2) (1) = 5040 
8! = (8) (7) (6) (5) (4) (3) (2) (1) = 40320 
9! = (9) (8) (7) (6) (5) (4) (3) (2) (1) = 362880 
10! = (10) (9) (8) (7) (6) (5) (4) (3) (2) (1) = 3628800 



Listing 13-1 shows a program called IF ACT that computes values of the Factorial 
function using iteration. The variable F is declared as a FIXED BINARY data item 
that accumulates the value of the factorial up to a maximum of 32767. 

Listing 13-2 shows the output from IFACT. IFACT gives the proper value for the 
Factorial function up to 7!, 5040. At this point, the variable F overflows and produces 
improper results, but the output continues. 

Note: PL/I does not signal FIXED OVERFLOW for binary computations. 

Listing 13-3 shows the program RFACT that performs the equivalent evaluation of 
the Factorial function using recursion. For comparison, RFACT uses the REPEAT form 
of the DO-group to control the test. RFACT declares factorial as a RECURSIVE 
procedure, and calls the procedure at the top level in the PUT statement on line 10. 



154 



PL/I Programming Guide 



13.1 The Factorial Function 



Line 19 contains an embedded recursive call in the RETURN statement. Factorial 
returns when the input value is zero. All other cases require one or more recursive 
evaluations of factorial to produce the result. For example, 3! produces the sequence 
of computations, 



factorial(3) = 



3* factorial^) 


= 




factorial (2) 


2*factorial(l) 






factorial 1) 


= l*factorial(0) 
factorial(O) 

= 1 1 




= 2 


1 * 1 


3 


2 


1 * 1 



= 1 



producing the value 6. Listing 13-4 shows the output for the recursive factorial eval- 
uation produced by RFACT. The values again overflow beyond 5040 due to the pre- 
cision of the computations. 



l 

2 
3 

a 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

1G 

17 



/a***************************************/ 
/* This program evaluates the Factorial */ 
/* function (n!) usinS iteration. */ 

-if act : 

procedure options (Main ) i 
declare 

( i » n» F) fixed! 



-do i = by 1 5 
F = 15 

do n = i to 1 by -1! 
F = n * F i 
I — end i 

put edi t ( v facto rial (' »i » ') = ' >F) 
(skip, a,f (2) » a> f (7) ) 5 
end i 



18 b I — end if act i 



Listing 13-1. The IFACT Program 
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A>i fact 










facto r: 


a 


( 0) = 


1 




factor: 


a 


U 1) = 


1 




factor: 


a 


l( Z) = 


2 




facton 


a 


l( 3) = 


B 




factor: 


a 


l( 4) = 


24 




factor: 


a 


l( 5) = 


120 




factor: 


a 


l( G) = 


720 




factor: 


a 


U 7) = 


5040 




facto n 


a 


( 8) = 


-2521S 


v the values are incorrect 


facto n 


a 


( 9) = 


-30338 


from this point on 


facto ri 


a 


(10) = 


24320 




facto n 


a 


(11) = 


5376 




factor] 


a 


(12) = 


-1024 




facto n 


a 


(13) = 


-13312 




facton 


a 


(14) = 


10240 




facto n 


a 


(15) = 


22528 




facton 


a 


(16) = 


-32768 




facto n 


a 


(17) = 


-32768 




facto n 


a 


(18) = 







facto n 


a 


(19) = 








Listing 13-2. Output from the IFACT Program 



1 


a 


/***#*#**##***♦*******♦###*##********♦***/ 


2 


a 


/* 


This program evaluates the Factorial */ 


3 


a 


/* 


function (n!) usinS recursion. */ 


4 


a 


/*#**#**#********#####*##****##*#*######*/ 


5 


a 


— rf act : 


6 


b 




procedure opt i ons (wain ) ! 


7 


b 




declare 


8 


b 




i fixed! 


8 


c 




i — do i = repeat ( i + 1 ) j 


10 


c 




put skip 1 ist (' facto rial (' >i >') = ' tfacto rial ( i )) 5 


11 


c 




— end 5 


12 


b 




stop ; 


13 


b 







Listing 13-3. The RFACT Program 
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14 b 




— f a c t o 


15 c 






IB c 






17 c 






18 c 






19 c 






20 c 




— end f 


21 b 






22 b 


— enc 


rf act ! 



procedure(i) returns(fixed) recursive! 
declare 

i fixed! 
if i = then return ( 1 ) i 
return (i * facto rial ( i -1 )) ! 



A>fact 



Listing 13-3. (continued) 



fact 
fact 
fact 
fact 
fact 
fact 
fact 
fact 
fact 
fact 
fact 
fact 
fact 
fact 
fact 
fact 
fact 
fact 
fact 
fact 



o ri al 
o ri al 
o ri al 
o rial 
o rial 
o ri al 
o ri al 
o ri al 
o ri al 
o ri al 
o ri al 
o ri al 
o ri al 
o ri al 
o rial 
o rial 
o rial 
o r i al 
o rial 
o ri al 



0) = 


1 




1) = 


1 




2) = 


2 




3) = 


G 




4) = 


24 




5) = 


120 




G) = 


720 




7) = 


5040 




8) = 


-2521G 


the values are incorrect 


9) = 


-30336 


from this point on 


10) = 


24320 




11) = 


5376 




12) = 


-1024 




13) = 


-13312 




14) = 


10240 




15) = 


22528 




16) = 


-32768 




17) = 


-32768 




18) = 







18) = 








Listing 13-4. Output from the RFACT Program 



157 



13.2 DECIMAL/BINARY Evaluation 



PL/I Programming Guide 



13.2 FIXED DECIMAL and FLOAT BINARY Evaluation 

The Factorial evaluation programs here illustrate an important point about arithmetic 
calculations using different data types. Listing 13-5 shows a program called DFACT. 
It is the same recursive evaluation of the Factorial function found in RFACT, but it 
uses the FIXED DECIMAL data with the maximum allowable precision. Listing 13-6 
shows the output from DFACT. The largest value produced by the program is: 

Factorial(17) = 355,687,428,096,000 

At this point, the run-time system signals FIXEDOVERFLOW to indicate that the 
decimal computation has overflowed the maximum 15 digit value. 

Listing 13-7 shows the program FFACT that evaluates the Factorial function using 
FLOAT BINARY data. Listing 13-8 shows the output from FFACT. FFACT can com- 
pute the value of the function beyond 17. PL/I truncates the number of significant digits 
on the right to approximately 7 equivalent decimal digits. Again, FFACT ends when 
the run-time system signals the OVERFLOW condition because the program produces 
an exponent value that cannot be maintained in the floating-point representation. 



1 a /##*******#******#*#*****#*********#**#*******#*#*/ 

2 a /* This program evaluates the Factorial function */ 

3 a /* (n!) using 1 recursion and FIXED DECIMAL data. */ 

4 a /#**********#******************************#**#***/ 

5 a | — df act : 

B b procedure options(main)! 
7b declare 
b i fixed i 

c i — do i = repeat(i + l)5 

put sKip 1 ist ( 'Facto rial (' >i » ') = ' tfacto rial ( i )) ! 
-end 5 
stop i 



9 
10 
11 
12 
13 
14 
15 
IB c 
17 c 
IB c 

19 c 

20 c 

21 c 

22 c 

23 b 

24 b 



factorial: 

procedure(i) retu rns ( f ixed decimal ( 15 >0) ) 

recursive 5 
declare 

i fixed? 

if i = then return (1)5 
return ( dec imal ( i 1 15) * facto rial ( i-1 )) 5 
■ end facto rial 5 



— end df act i 



Listing 13-5. The DFACT Program 
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f\>dfact 






Factorial 


0) = 


1 


Factorial 


1) = 


1 


Facto rial 


2) = 


2 


Facto rial 


3) = 


B 


Factorial 


a) = 


24 


Facto rial 


5) = 


120 


Facto rial 


G) = 


720 


Factorial 


7) = 


5040 


Facto rial 


8) = 


40320 


Facto rial 


9) = 


382880 


Facto rial 


10) = 


3628800 


Facto rial 


11) = 


39918800 


Facto rial 


12) = 


479001600 


Factorial 


13) = 


6227020800 


Facto rial 


14) = 


87178281200 


Facto rial 


15) = 


1307674388000 


Facto rial 


16) = 


20922789888000 


Factorial 


17) = 


355887428096000 


Facto rial 


18) = 




FIXED OMEF 


?FLOW (1) 




Trace bacK 
A> 


0007 019F 0018 


0000 # 2809 8874 



Listing 13-6. Output from the DFACT Program 



l 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

IB 

17 

18 

19 

20 

21 

22 



/* This program evaluates the Factorial function */ 
/# (n!) usin* recursion and FLOAT BINARY data. */ 

-f f act : 

procedure options (-main) I 
declare 

i fixed! 
-do i = repeat ( i+1 ) i 

put skip 1 i st ( v Facto rial ( * » i t ') = ' tfacto ri al ( i )) ! 
■ end 5 
stop ! 



■factorial: 

procedure(i) re tu rns ( f loat ) recursive; 
declare 

i fixed! 
if i = then return (1)5 
return (i * f acto ri al ( i- 1 ) ) i 
1 — end factorial! 



-end ffact; 



Listing 13-7. The FFACT Program 
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Pi>ffact 



Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factori a 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

Factoria 

OVERFLOW 

TracebacK 

A> 





1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 

22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

1) 

00BC 13CB 



) = 



) = 



0O0000E+O0 
000000E+00 
0OOOO0E+O0 
600000E+01 
400000E+01 
200000E+02 
720000E+03 
504000E+04 
032000E+04 
B28799E+05 
B28799E+0B 
991B79E+07 
790015E+0B 
622702E+10 
871782E+11 
307674E+12 
092278E+13 
55B874E+14 
B40237E+1B 
216450E+17 
432901E+18 
510909E+20 
124000E+21 
585201E+22 
620448E+24 
551121E+25 
032914E+2G 
088887E+28 
04B883E+29 
8B417BE+31 
652528E+32 
822283E+34 
G31308E+35 
8B8331E+37 



019B 0000 * 8B08 0B15 FB51 0141 



Listing 13-8. Output from the FFACT Program 
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13.3 The Ackermann Function 

The PL/I run-time system maintains a 512-byte stack area to hold subroutine return 
addresses and some temporary results. Under normal circumstances, this stack area is 
sufficiently large for nonrecursive and most simple recursive procedure processing. The 
program in this section, however, illustrates multiple recursion using a stack depth 
that can exceed the 512-byte default value. 

The Ackermann function, denoted by A(m,n), comes from Number Theory and has 
the following recursive definition: 

* 

In + 1 if m = 0, otherwise 

A(m-l,l) if n = 0, otherwise 
A((m-1), A(m,n-1)) 

Listing 13-9 shows the ACK program that reads two values for the maximum m 
and, n on line 11, and then evaluates the function for these values. Listing 13-10 shows 
the program interaction. Although the Ackermann function returns a FIXED BINARY 
value, the program uses the built-in DECIMAL function to control the size of the 
converted field in the PUT statements on lines 12, 15, and 17. 

In this example, ACK uses the STACK option on line 7 to increase the size of the 
run-time stack from its default value, 512 bytes, to 2000 bytes. 

Note: the STACK option is only valid with the MAIN option. You must determine 
the value of the STACK option empirically, because the Compiler cannot compute the 
depth of recursion. If the allocated stack size is too small and the stack overflows 
during recursion, the run-time system outputs the message: 

FREE SPACE OVERWRITE 

and then ends the program. 

This kind of multiple recursion processing is CPU intensive. You should experiment 
with some different values for max, and see if you can determine how much stack is 
being used. 
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l 

2 
3 

a 

5 

6 

7 

8 

9 
10 
11 
12 

13 b 

14 c 

15 c 

16 d 

17 d 

18 d 

19 c 

20 b 

21 b 

22 b 

23 c 

24 c 

25 c 
28 c 

27 c 

28 c 

29 c 

30 c 

31 b 

32 b 



/**#####**********#**#***#*****#**********##*#*##**♦/ 
/* This program evaluates the Ackermann function */ 
/* A ( m » n ) t and increases the size of the stack */ 
/* because of the larSe number of recursive calls. */ 
/****#*#*#**#**♦###**#**#*#*##***##***#*****#*###**#/ 
-ack: 

procedure options (Main tstack(2000) ) i 
declare 

(m >maxm tn >maxn ) fixed? 
put skip listt'Type max nun: ')! 
Set list (maxm unaxn ) i 
put skip 

list(' '»( decimal (n »4) do n=0 to maxn))! 

-do m = to maxm ! 

put skip 1 ist ( de cimal ( m >4 )»*:') ! 
do n = to maxn i 

put list(decimal(ackerhiann(Min) »4) ) 5 
end ! 
-end ! 
st op ! 



acke rmann : 

procedure (m >n ) retu rns ( f i xed ) recursive! 
declare (m»n) fixed? 
if m = then 

return (n + 1 ) ! 
if n = then 

return(ackermann(m-l tl) ) 5 
return(acKermann(hi-l >ackermann(m>n-l))) ! 
•end ackermann? 



-end ack! 



A>acA' 



Type wax m > n : *3 >5 



A> 



Listing 13-9. The ACK Program 








1 


2 


3 


4 


5 


0: 


1 


2 


3 


4 


5 


G 


1: 


2 


3 


a 


5 


G 


7 


2: 


3 


5 


7 


9 


11 


13 


3: 


5 


13 


29 


61 


125 


253 



Listing 13-10. Interaction with the ACK Program 
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13.4 An Arithmetic Expression Evaluator 

One of the practical uses of recursion is the translation of statements in a high-level 
programming language. This is because most languages are defined recursively. In 
block-structured languages like PL/I for example, DO-groups and BEGIN and PRO- 
CEDURE blocks can all be nested, and the resulting structure lends itself easily to 
recursive processing. 

The next example illustrates how you can use recursion to evaluate arithmetic expres- 
sions. Here is a simple, recursive definition of an arithmetic expression: An expression 
is a simple number, or a pair of expressions separated by a +, — , *, or /, and enclosed 
in parentheses. 

Using this definition, the number 3.6 is an expression because it is a simple number. 
Clearly, 

(3.6 + 6.4) 

is an expression because it consists of a pair of expressions that are both simple numbers, 
separated by a + , and enclosed in parentheses. Also, 

(1.2* (3.G + 6.4) ) 

is a valid expression because it contains the two valid expressions 1.2 and (3.6 -I- 6.4), 
separated by a * and enclosed in parentheses. 

Using the definition given above, the sequences, 

3.6 + 6.4 

(1.2+ 3.G + 6.4) 

are not valid expressions because the first is not enclosed in parentheses, while the 
second is not a pair of expressions in parentheses. 

The preceding definition of an expression is somewhat restricted, but once established, 
you can expand it to include more complex expressions. 
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Listing 13-11 shows an expression evaluation program called EXPR1. The main 
processing takes place between lines 27 and 31 where EXPR1 reads an expression from 
the console and types the evaluated result back to you. Listing 13-12 shows the console 
interaction with EXPR1 where the user enters several properly and improperly formed 
expressions. 



1 a 

2 a 

3 a 
a a 
5 a 
G a 

7 a 

8 a 



9 
10 
11 
12 



13 b 

14 b 



15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
2G 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 



/#*****#*******#****♦***#**************#*##****#**###*#*/ 
/* This program evaluates an arithmetic expression */ 
/# usins recursion. It contains two procedures. GNT */ 
/* obtains the input expression consisting of separate */ 
/* toKenst and EXP that performs the recursive */ 
/* evaluation of the toKens in the input line. */ 

-expression: 

procedure options (main) i 
declare 

sysin filet 

value float > 

toKen cha racte r ( 10 ) varying! 

on endfile(sysin) 
st op i 



on error(i) /* conversion or siSnal #/ 
-be S in ! 

put skip list(Mnvalid Input at 'ttoKen)! 

Set skip 5 

Soto restart i 
-end i 



restart : 



-do while(M'b)i 

put skip(3) listt'Type expression: 

value = exp()i 

put skip list( M Jalue i s : ' » v a 1 u e ) 5 
-end i 



-Snt : 

procedure i 
Set list (token ) ; 
end 3nt i 



') ; 



Listing 13-11. The EXPRESSION Program using Evaluator EXPR1 
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38 b 




— exp : 






39 c 




procedure returns(float binary) recursive! 


40 c 




declare x float binary! 


41 c 




call ant ( ) ! 


42 c 






— if token = '(' then 


43 d 








— do! 


44 d 








x = exp ( ) ! 


45 d 








call 4nt ( ) ! 


4B d 








. | — if token = v + ' then 


47 d 










x = x + exp ( ) ! 


48 d 










— e 1 se 


49 d 








i — i f token = v - ' then 


50 d 










x = x - exp ( ) ! 


51 d 










— e 1 se 


52 d 








i — if token = '*' then 


53 d 










x = x * exp ( ) ! 


54 d 










— else 


55 d 








l — if token = V' then 


56 d 










x = x / exp ( ) ! 


57 d 










— e lse 


58 d 








si anal error(l)! 


59 d 








call ant( ) ! 


GO d 








if token "= ' ) ' then 


61 d 








s i anal e r ro r ( 1 ) 5 


G2 d 








— end ! 


63 c 






' — e 1 se 


64 c 




x = token 5 


65 c 




re tu rn ( x ) i 


66 c 




— end exp ! 


67 b 




68 b 


e nd expression! 












Listing 13-11. (continued) 



13.4.1 The Exp Procedure 

The heart of the expression analyzer is the RECURSIVE procedure exp. This pro- 
cedure implements the recursive definition given above and decomposes the input 
expressions piece by piece. The GNT, Get Next Token, procedure reads the next element 
or token, a left or right parenthesis, a number, or one of the arithmetic operators in 
the input line. GNT uses a GET LIST statement, so you must separate each token with 
a blank or end-of-line character. 



rO DIGITAL RESEARCH 
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On line 41, exp calls GNT. GNT places the next input token into the CHARAC- 
TER^ 10) variable called token. If the first item is a number, then the series of tests in 
exp sends control to line 64. The assignment to x automatically converts the value of 
token to a floating-point value. Then exp returns this converted value to line 29, where 
EXPR1 stores it into value, and subsequently writes it out as the result of the expression. 

If the expression is nontrivial, then exp scans the leading left parenthesis on line 42, 
and enters the DO-group on line 43. EXPR1 immediately evaluates the first sub- 
expression no matter how complicated, and stores it into the variable x on line 44. 
EXPR1 then checks token for an occurrence of +,—,*, or /. Suppose, for example, 
token contains the * operator. The statement on line 53 recursively invokes the exp 
procedure to evaluate the right side of the expression. Upon return, it multiplies this 
result by the value of the left side that was previously computed. EXPR1 then checks 
the balancing, right parenthesis starting on line 60, and returns the resulting product 
as the value of exp on line 64. 

13.4.2 Condition Processing 

EXPR1 performs condition processing in three places. The first ON-unit, line 15, 
intercepts an end-of-file, CTRL-Z, condition on the input file, and executes a STOP 
statement. The second ON-unit, line 18, receives control if an error occurs during 
conversion from character to floating-point representation at the assignment on line 
64. The ON-unit displays the token in error, and then executes a GET SKIP statement 
to clear the data to the end of the line. It then transfers control to the restart label, 
which prompts for another input expression. 

EXPR1 signals a condition when it encounters an invalid operator or an unbalanced 
expression. If the operator is not a +,—,*, or /, then EXPR1 executes line 58 and 
signals the ON-unit, line 18. Again, the ON-unit displays the error and transfers control 
to the restart label. Similarly, a missing right parenthesis on line 60 triggers the ERROR(l) 
ON-unit to report the error and restart the program. When the program restarts, 
PL/I discards the information on the current level of recursion. 
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(\>exprl 



Type expression: C 4 + 5,2 ) 
Value is: 0.920000E+01 

Type expression: 4,5e-l 
Value is: 4 .499999E-01 

Type expression: (445) 
Inualid input at & 

Type expression: ( ( 3 + 4 ) - (10 / 8 ) ) 
Value is: 0.575000E+01 

Type expression: (3*4) 
Value is: 1.200000E+01 

Type Expression: '"Z 
A> 

Listing 13-12. Interaction with EXPR1 

13.4.3 Improvements 

The expression analyzer requires spaces between tokens in the input line. Recall that 
Section 11.2 contains a more advanced version of GNT. 

We incorporate this expanded version of GNT into the expression analyzer, and 
also change the error recovery mechanism so that now line 27 discards the remainder 
of the current input when restarting the program. Listing 13-13 shows the improved 
version called EXPR2, and Listing 13-14 shows the console interaction with this improved 
expression evaluator. 
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Even in EXPR2 there is room for expansion. First, you can add more operators to 
expand upon the basic arithmetic functions. Also, you can add operator precedence 
and eliminate the requirement for explicit parentheses. Beyond that, you can add 
variable names and assignment statements to turn the program into a BASIC interpreter! 



3 
10 


a r 
b 


11 


b 


12 


b 


13 


b 


14 


b 


15 


b 


16 


b 


17 


b 


18 


b 


19 


b 


20 


b 


21 


b 


22 


b 


23 


b 


24 


b 


25 


c 


26 


c 


27 


c 


28 





29 


c 


30 


b 


31 


b 


32 


b 


33 


c 


34 


c 


35 


c 


36 


c 


37 


c 


38 


b 



/* This program evaluates an arithmetic expression */ 

/* usinS recursion. It contains an expanded version */ 

/* of the GNT procedure that obtains an expression */ 

/* containing separate tokens. EXP then recursively */ 

/* evaluates the tokens in the input line. */ 
/♦a***************************************************/ 

•expression : 

procedure options (wain ) i 



1 repl ace 

t rue by M'bi 

declare 

sysin file* 

value floatt 

(token charac te r( 10 ) i line characte r(80 ) ) varying 

static ini tial ( w ) 5 

on endfi le ( sysin ) 
stop ! 

on error(l) /* conversion or signal */ 
-be Sin ! 

put skip 1 ist( ' Invalid Input at '»toKen)5 

token = * * ! line = ' ' i 

Soto restart! 
-end 5 

restart : 

— do whi le ( M ' b ) 5 

put skip(3) list('Type expression: ')5 

value = exp( ) 5 

put editf'Malue is: Svalue) ( skip >a »f ( 10 »4) ) ! 
— end i 



Listing 13-13. (continued) 
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39 


b 


40 


c 


41 


c 


42 


c 


43 


c 


44 


c 


45 


d 


46 


d 


47 


d 


48 


d 


49 


d 


50 


d 


51 


d 


52 


e 


53 


e 


54 


e 


55 


e 


56 


e 


57 


e 


58 


e 


59 


B 


60 


e 


61 


e 


62 


e 


63 


e 


64 


d 


65 


c 


66 


b 



procedure ! 
declare 

i fixed! 

line = subs t r ( 1 ine » 1 en St h ( t oKen ) + 1 ) i 
— do wh i le ( t rue ) ! 

if line = w then 

Set edit(line) (a)i 
i = verify(line»' ')! 
if i = then 
line = w 5 
else 

, do i 

line = subst r ( 1 ine » i ) ! 
i = uerif/Uine » ^0123456789 . ') ! 
if i = then 
toKen - line! 
1 — else 

-if i = 1 then 

toKen = subs t r ( 1 ine » 1 > 1 ) ! 
else 

toKen = substr(linetl»i-l)» 
return! 
— end ! 



-end ! 
-end Snt ! 



Listing 13-13. (continued) 
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67 b 

68 o 

69 c 

70 c 

71 c 

72 d 

73 d 

74 d 

75 d 

76 d 

77 d 

78 d 

79 d 

80 d 

81 d 

82 d 

83 d 

84 d 

85 d 

86 d 

87 d 

88 d 

89 d 

90 d 

91 d 

92 c 

93 c 

94 c 

95 c 

96 b 

97 b 



-exp: 

procedure re turns ( float binary) recursive! 
declare x float binary! 
call Snt ( ) ! 
-if toKen = M ' then 
-do 5 

x = exp( ) ! 
call 3nt( ) i 

— if toKen = * + ' then 
x = x + e x p ( ) ! 

— else 
I — if toKen = s - ' then 

x = x - exp( ) 5 

— else 
, — if token = '*' then 

x = x * exp( ) i 

— else 

— if token = V then 
x = x / exp( ) i 

— else 
signal error(l)! 
call «fnt( ) 5 
if token A = M ' then 

si sfnal e rro r( 1 ) 5 
-end 5 
-else 

x = token 5 
return ( x ) 5 
-end exp! 



-end expression? 



Listing 13-13. Expression Evaluator EXPR2 
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<\>expr2 

Type expression: ( 2 * 14,5 ) 

Value is: 29.0000 

Type expression: C (2*3) / (4,3-1.5)) 
Value is: 2. 1429 

Type expression: zot 
Invalid Input at z 

Type expression: ((2*3) -5) 
Value is: 1.0000 

Type expression: (2 n5) 
Invalid Input at n 

Type expression: '"I 
A> 

Listing 13-14. (continued) 

End of Section 13 
References: Sections 2.8-2.9, 3.1-3.2, 4.2, 9 LRM 
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Section 14 
Separate Compilation 



All of the programs presented so far are single, complete units, although many contain 
one or more internal procedures. It is often useful to break larger programs into distinct 
modules to be subsequently linked with one another and with the PL/I Run-time 
Subroutine Library (RSL). 

There are two reasons for separately compiling and linking programs in this manner. 
First, large programs take longer to compile. Smaller segments can be independently 
developed, tested, and integrated, requiring less overall compilation time for the entire 
project. A large program can also overrun the memory space available for the Symbol 
Table. 

Second, particular subroutines are useful for your own application programming. 
You can build your own library of subroutines and selectively link them to your 
programs. Having such a library of common subroutines greatly reduces the overall 
development time for any particular program. 

This section presents basic information required to link program segments. It also 
presents an example of a program that is compiled as two separate modules and then 
linked together. 



14.1 Data and Program Declarations 

You can direct separate modules to share data areas by including the EXTERNAL 
attribute in the declaration of the data item. For example, the statement, 

declare x ( 1 ) fixed binary external? 

defines a variable named x occupying 10 FIXED BINARY locations, 20 contiguous 
bytes, that is accessible by any other module that uses the same declaration. 



173 



14.1 Data and Program Declarations PL/I Programming Guide 



Similarly, the statement, 

declare 

1 s external* 
2 y ( 1 ) b i t ( 8 ) » 
2 zcharacterO) u a r y i n sf 5 

defines a structure named s, occupying a 20-byte area that is accessible by any other 
modules that use the same declaration. 

The following list summarizes basic rules that apply to the declaration of external 
data: 

■ EXTERNAL data items are accessible in any block in which you declare them. 
The EXTERNAL attribute overrides the scope rules for internal data. 

■ Initialize an EXTERNAL data item in only one module. Other modules can 
then reference the item. 

■ Declare all EXTERNAL data areas with the same length in all modules in which 
they appear. 

■ In the 8080 implementation, EXTERNAL data items must be unique in the 
first six characters because the linkage editing format truncates from the seventh 
character on. In the 8086 implementation, there is no such restriction. 

■ Avoid using ? symbols in variable names, because this character is used as a 
prefix for names in the RSL. 

■ Remember that PL/I automatically assigns the STATIC attribute to any EXTER- 
NAL data item. 



14.2 ENTRY Data 

ENTRY constants and ENTRY variables are data items that identify procedure 
names and describe their parameter values. ENTRY constants correspond to external 
procedures, or procedures defined in the main procedure. 
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ENTRY variables take on ENTRY constant values during program execution through 
a direct assignment statement, or an actual-to-formal parameter assignment implicit 
in a subroutine call. 

You invoke a procedure directly through a call to an ENTRY constant, or indirectly 
by calling a procedure constant value held by an ENTRY variable. As with label 
variables, you can also subscript ENTRY variables. 

The program shown in Listing 14-1 illustrates ENTRY data. The ENTRY variable 
f declared on line 8 is an array containing three ENTRY constants. Starting on line 
12, the program initializes the subscripted elements to the constants a, b, and c respec- 
tively. Note that the constant a corresponds to an externally compiled procedure (see 
Listing 3- la). 

The ENTRY variable called f declared on line 8 contains three elements. Starting 
on line 13, the program initializes the individually subscripted elements to the constants 
sin, g, and h, respectively. 

On line 16, the DO-group prompts for input of a value to send to each function, and 
then on line 19 calls each function once with the invocation, 

f ( i ) (x) 

where the first parenthesis pair defines the subscript, and the second encloses the list 
of actual arguments. 

The declaration of ENTRY constants and ENTRY variables is similar to FILE con- 
stants and FILE variables. PL/I assumes all formal parameters declared as type ENTRY 
to be entry variables. In all other cases, an entry is constant unless you declare it with 
the VARIABLE keyword. 

The following rules apply to external procedure declarations: 

■ You can access data items with the EXTERNAL attribute in any procedure 
where they are declared EXTERNAL. 

■ In the 8080 implementation, you must make external procedure names unique 
in the first six characters (see Section 14.1). In the 8086 implementation, there 
is no restriction. 

■ Avoid using the ? symbol in procedure names. 
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Note: in addition, you must ensure that each formal parameter exactly matches the 
actual procedure declaration, and that the RETURNS attribute exactly matches the 
form returned for function procedures. 



1 a 

2 a 

3 a 
a a 
5 a 
B h 

7 b 

8 b 

9 b 

10 b 

11 b 

12 b 

13 b 

14 b 

15 b 
1G c 

17 c 

18 c 

19 c 

20 c 

21 b 

22 b 

23 b 

24 c 

25 c 
2B c 

27 c 

28 b 

29 b 

30 c 

31 c 

32 c 

33 c 

34 b 

35 b 



/ft**********************************************-*/ 
/* This program illustrates ENTRY variables and */ 
/♦constants. * / 

/♦a**********************************************/ 
-call: 

procedure options(wain) i 
declare 

f(3) ent ry( float ) return s(float) variable* 
a en try (float) returns(float)» 
i fixed t x float! 

f(l) = ai 

f(2) = b! 
f(3) = ci 



•do i = 1 to 3 5 

put s K i p 1 i s t ( ' T y p e x ' ) 5 

Set list ( x ) 5 

put 1 i s t ( ' f ( ' > i i ' ) = ' > f ( i ) ( x ) ) 5 
-end 5 
stop ! 

r-b: 

procedure(x) ret urns ( f 1 oat ) 5 /* internal procedure */ 

declare x float! 

return (2*x +1)5 
■—end b ! 



procedure(x) ret u rns ( f 1 oat ) ! /* internal procedure */ 
declare x float! 
ret u rn ( s in ( x ) ) ! 
e n d c ! 



■end call! 

Listing 14-1. An Illustration of ENTRY Constants and Variables 



14.3 An Example of Separate Compilation 

This section presents an example program of two modules that are compiled sepa- 
rately and then linked together. The two modules are called MAININVT and INVERT, 
and are shown in Listings 14-2 and 14-3, respectively. Compiling each of these modules 
and then linking them together produces a program that interacts with the console to 
produce the solution set for a system of simultaneous equations. 



176 



PL/I Programming Guide 14.3 An Example of Separate Compilation 

To understand how the programs work, first consider the following system of equa- 
tions in three unknowns: 

a-b + c = 2 a - b + c = 3.5 

a + b - c = a + b - c = 1 

2a - b =0 2a - b =-1 

The values, 

a = 1 a = 2.25 

b = 2 and b = 5.50 
c = 3 c = 6.75 

constitute valid solutions to this system of equations, because: 

1-2 + 3 = 2 2.25 - 5.50 + 6.75 = 3.50 

1 + 2-3 = and 2.25 + 5.50 - 6.75 = 
2*1-2 =0 2*2.25 - 5.50 = 

The values 2,0,0 and 3.5,0,0 are called solution vectors for the matrix. The coefficients 
of the matrix are: 

1 -1 1 
1 1 -1 
2-10 

The MAININVT module interacts with the console to read the coefficients and the 
solution vectors for a system of equations. The INVERT module performs the actual 
matrix inversion that solves the system of equations. 

The essential difference between these two modules is found in the procedure heading. 
The maininvt procedure is the main program because it is defined with the MAIN 
option. The invert procedure is a subroutine called by the main program. In Listing 
14-2, the declaration starting on line 15 defines invert as an EXTERNAL entry constant 
that is then called on line 49. 

On line 21, MAININVT declares the parameters for the invert procedure as a matrix 
of floating-point numbers denoted by maxrow and maxcol. Invert is defined with two 
additional FIXED(6) parameters, but does not return a value. 

The invert procedure, shown in Listing 14-3 has three formal parameters called a, 
r, and c. They are defined on line 2 and declared in lines 7 and 8. INVERT takes the 
actual values of maxrow and maxcol, corresponding to the largest possible row and 
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column value, from a % INCLUDE file, as indicated by the + symbols following the 
line number at the left of both listings. 

After you compile both of the modules, link them together with the command: 
A > I i n H i n vmat =mai n i n v t ti n vert 

The linkage editor combines the two modules, selects the necessary subroutines from 
the RSL, and creates the command file, named INVMAT. 

Listing 14-4 shows the interaction with INVMAT. In this sample interaction, the 
user first enters the identity matrix to test the basic operations. The inverse matrix 
produced for this input value is also the identity matrix. 

The user then enters the system of equations shown above, along with two solution 
vectors. The output values for this system are shown under Solutions: and match the 
values shown above. The second set of solutions corresponds to the second solution 
vector input. 

Finally, the user tests INVMAT with an invalid input matrix size, and then ends the 
program by entering a zero row size. 



l 

2 
3 

4 

5 

e 

7 

8 

9 

10 



11 + b 
12+b 
13+b 
14 b 



15 
16 
17 
18 
19 
20 
21 
22 
23 



•/* This program is the main module in a program that */ 
/* performs matrix inversion. It calls 'the entry */ 
/* constant INVERT which does the actual inversion. */ 

maininvt : 

procedure options (main ) 5 
%replace 



true by 


M 


b 


false by 


*0 


b 


X replace 






maxrow by 


2G 




maxco 1 by 


40 





declare 

mat (max row tmaxcol ) float binary(24)» 

( i t J >n »m) f ixed (S) > 

var character (26) static initial 

('abcdefShiJKlmnopirstuuwxyz') > 

invert entry 

( (maxrow»maxcol ) float(24)» fixed(G)» fixed(B))! 

put 1 ist ( 'Solution of Simultaneous Equations')! 

Listing 14-2. MAINENVT - Matrix Inversion Main Program Module 
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24 c 

25 c 

26 c 

27 c 

28 c 

29 c 

30 c 

31 c 

32 c 

33 c 
3a d 

35 d 

36 d 

37 e 

38 e 

39 e 

40 e 

41 d 

42 d 

43 d 

44 e 

45 e 

46 e 

47 e 

48 d 

49 d 

50 d 

51 e 

52 e 

53 e 

54 e 

55 e 
5B d 

57 d 

58 e 
58 e 
BO e 

61 e 

62 d 

63 c 

64 b 

65 b 



-do wh i le ( t rue ) i 

put skip(2) list('Type rows t columns: ')! 
Set list (n ) i 
if n = then 
stop ! 



Set 1 i st ( m ) 5 

if n > maxrow ! m > maxcol then 

put sKip list('Matrix is Too L a r S e ' ) 5 
else 
do ; 

put skip list('Type Matrix of Coefficients')! 
put skip ! 
— do i = 1 to n i 

put 1 ist ( 'Row ' »i > ' : ' ) i 
Set 1 ist ( (Mat ( i » J) do j = 1 to n)>5 
— end 5 



put skip list('Type Solution Vectors')! 
put skip ! 
-do J = n + 1 to m! 

put list( 'Variable' »substr(variJ-n »1) » x : ') ! 
Set 1 ist ( (mat ( i > J ) do i = 1 to n))i 
-end ! 

call inue rt (mat >n >m) ! 
put skip(2) list ( 'Solutions: ') ! 
-do i = 1 to n 5 

put skip 1 ist ( subst r( uar »i tl )>' = ') ! . 
put edi t ( (mat ( i » J ) do j = 1 to m-n)) 
(f (8,2)) ! 
I — end! 

put skip(2) 1 ist ( ' Inve rse Matrix is')! 
i — do i = 1 to n ! 

put skip edit ( (mat ( i > J ) do j = m-n+1 to m)) 
(x(3) »6f (8»2) tskip) ! 
-end ! 
— end 5 
-end! 

end main inut 5 



Listing 14-2. (continued) 



^RESE! 



tOPRJET 



DIGITAL RESEARCH 
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1 a 


1 — inve rt : 










2 b 


procedure ( a t r >c ) i 






3+b 


^replace 






4+b 


max ; ow by 26 » 






5+b 


maxcol by 40 5 






6 b 


declare 






7 b 


(d» a(max row xnaxcol ) ) float binary(24) 


> 


8 b 


( i > J »K »1 » r »c ) fixed binary(6)> 






9 c 




1 do i = 1 to ri 






10 c 




d = a(i »1) i 






11 d 






— do J = 1 to c - 1 5 






12 d 






a( i » J ) = a( i > J+l ) /d i 






13 d 






— end 5 






14 c 




a( i »c ) = 1/d 5 






15 d 






— do k = 1 to r5 






16 d 






if k "= i then 






17 e 








— do i 






18 e 








d = a(k.l) ; 






19 f 










— do 1 = 1 to o - 1 ! 






20 f 










a(k »1) = a(k .1 + 1) - a 


i »1) * 


di 


21 f 










— end 5 






22 e 








a(k »c) = - a( i »c) * d i 






23 e 








— end J 






24 d 






end5 






25 c 




end 5 






26 b 








27 b 


— e 


nd 


nue rt 











Listing 14-3. INVERT - Matrix Inversion Subroutine 



A>in vmat 

Solution of Simultaneous Equations 

Type rows* columns: 3>3 

Type Matrix of Coefficients 
Row 1:10 
Row 2 :0 1 
Row 3 :0 1 

Type Solution Vectors 



Listing 14-4. Interaction with the INVMAT Program 
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Solutions 
a = 
b = 



Inverse Matrix is 

1 .00 0.00 .00 

0.00 1.00 0,00 

0.00 0.00 1.00 

Type rows* columns: 3»5 

Type Matrix of Coefficients 
Row 1 : 1 - 1 1 
Row 2 :1 1 -1 
Row 3 :2 -1 

Type Solution Vectors 
Variable a :2 
Variable b :3.5 1 -1 



Solutions: 

a = 1.00 2.25 

b = 2.00 5.50 

c = 3.00 G.75 

Inverse Matrix is 

0.50 0.50 0.00 

1.00 1.00 -1,00 

1.50 0.50 -1.00 

Type rows* columns: 41 tO 

Mat rix is Too Lar^e 

Type rows » columns : 

A> 



Listing 14-4. (continued) 

End of Section 14 
References: Sections 3.3.2, 5.1-5.4, 8.2 LRM 
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Section 15 
Decimal Computations 



This section explains how PL/I handles decimal computations, stores decimal data, 
and converts data types. Study this material thoroughly because it is vital to under- 
standing commercial processing. 



15.1 A Comparison of Decimal and Binary Operations 

The arithmetic with which we are most familiar uses the decimal number system. 
All operations, such as addition and multiplication, are based on the number ten, and 
involve the digits zero through nine. Computers, however, perform arithmetic opera- 
tions using binary or base 2 numbers. Computers use binary numbers because the Is 
and Os can be directly processed by the on-off electronic switches found in arithmetic 
processors. 

Most programming languages allow you to write programs that process base 10 
constants and data items in simple and readable forms. Because the programs process 
decimal values, it is necessary to convert values into a binary form on input and back 
to a decimal form on output. This conversion from one type to another can introduce 
truncation errors that are unacceptable in commercial processing. Thus, decimal arith- 
metic is often required to avoid propagating errors throughout computations. 

In most programming languages, you have no control over the internal format used 
for numeric processing. In fact, two of the most popular BASIC interpreters for micro- 
processors differ primarily in the internal number formats. One uses floating-point 
binary, while the other performs calculations using decimal arithmetic. 

PASCAL Compilers generally use floating- and fixed-point binary formats with imple- 
mentation-defined precision, while FORTRAN Compilers always use floating- or fixed- 
point binary. 

COBOL on the other hand, was designed for use in commercial applications where 
exact dollars and cents must be maintained throughout computations. Therefore, COBOL 
processes data items using decimal arithmetic. 
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PL/I gives you a choice between representations, so that you can tailor the data in 
each program to the exact needs of the particular application. PL/I uses FIXED DEC- 
IMAL data items to perform commercial functions, and FLOAT BINARY items for 
scientific processing where computation speed is the most important factor, and trun- 
cation errors are insignificant or ignored altogether. 

The two programs shown below illustrate the essential difference between the two 
data types. 



d e c i m a 1 _ c o m p : 

procedure options (wain ) 5 
declare 
i fixed t 

t fixed deci(nal(7 »2) i 
t = 05 
-do i = 1 to 10000 5 

t = t + 3. 10! 
-end i 

put edit(t) (f (10>2)> 5 
end decimal-cowp 5 



-binarv-comp: 

procedure options (main ) 5 
declare 
i fixed > 

t float binary (24) 5 
t = 0! 

Edo i = 1 to 10000! 
t = t + 3.105 
end i 

put edit(t) (f (10»Z))5 
-end binary_coMP! 



Both of these programs sum the value 3.10 a total of 10,000 times. The only difference 
between these programs is that DECIMAL_COMP computes the result using a FIXED 
DECIMAL variable, while BINARY_COMP performs the computation using FLOAT 
BINARY. 

DECIMAL_COMP produces the correct result 31000.00, while BINARY_COMP 
produces the approximation 30997.30. The 2.70 difference is due to the inherent 
truncation errors that occur when PL/I converts certain decimal constants, such as 
3.10, to their binary approximations. DECIMALCOMP produces the exact result 
because no conversion occurs when using FIXED DECIMAL variables. 

These two programs illustrate a more general problem. Suppose that during a par- 
ticular day, Chase Manhattan Bank processes 10,000 deposits of $3.10. Using a pro- 
gram with FLOAT BINARY data, $3.10 cannot be represented as a finite binary 
fractional expansion. Therefore it is approximated in FLOAT BINARY form as 
3.099999E + 00. Each addition propagates a small error into the sum, resulting in an 
extra $2.70 unaccounted for at the end of the day. 
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There are also situations where decimal arithmetic produces truncation errors that 
can propagate throughout computations. For example, the fraction 1/3 cannot be 
represented as a finite decimal fraction, and thus is approximated as 

0.3333333 ... 

to the maximum possible precision. Such errors only occur when explicit division 
operations take place. 

The difficulty with FLOAT BINARY representations is that some decimal constants 
expressed as finite fractional expansions in FIXED DECIMAL cannot be written as 
finite binary fractions. PL/I necessarily truncates these during conversion to FLOAT 
BINARY form. 

There are both advantages and disadvantages in selecting FIXED DECIMAL arith- 
metic instead of FLOAT BINARY. One advantage of FIXED DECIMAL arithmetic is 
that it guarantees there is no loss of significant digits. All digits are considered significant 
in a computation, so that multiplication, for example, does not truncate digits in the 
least significant positions. Another advantage is that FIXED DECIMAL arithmetic 
precludes the necessity for exponent manipulation, and the operations are relatively 
fast when compared to alternative decimal arithmetic formats. 

The disadvantage is that you must keep track of the range of values that arithmetic 
operands can assume because all digits are considered significant. 



15.2 Decimal Representation 

Decimal variables and constants have both precision and scale. The precision is the 
number of digits in the variable or constant, while the scale is the number of digits in 
the fractional part. For FIXED DECIMAL variables and constants, the precision cannot 
exceed 15, and the scale cannot exceed the precision. 
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You can define the precision and scale of a variable in the variable declaration. For 
example, 

declare x fixed decimal(10»3)i 

declares the variable x to have precision 10 and scale 3. The Compiler automatically 
derives the precision and scale of a constant by counting the number of digits in the 
constant, and the number of digits following the decimal point. For example, the 
constant 

-324.76 

has precision 5 and scale 2. 

Internally, PL/I stores FIXED DECIMAL variables and constants as Binary Coded 
Decimal (BCD) pairs, where each BCD digit occupies either the high- or low-order 
four bits of each byte. The most significant BCD digit defines the sign of the number. 
A zero denotes a positive number, and a nine denotes a negative number in the 10's- 
complement form, as described below. Because PL/I always stores numbers into 8-bit 
byte locations, there can be an extra pad digit at the end of the number to align it to 
an even byte boundary. 

For example, PL/I stores the number 83.62 as, 



8 


3 6 


2 



where each digit represents a 4-bit half-byte position in the 8 -bit value. PL/I stores the 
leading BCD pair lowest in memory. 

PL/I stores negative numbers in 10's-complement form to simplify arithmetic oper- 
ations. A 10's-complement number is similar to a 2's-complement binary representa- 
tion, except the complement value of each digit x is 9-x. 

To derive the 10's-complement value of a number, form the complement of each 
digit by subtracting the digit from 9, and add 1 to the final result. Thus, the 10's 
complement of -2 is formed as follows: 

(9 -2) + 1 = 7 + 1 = 8 

PL/I adds the sign digit to the number that then appears as the single-byte value: 

9 8 
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Look at an example. Suppose you want to add — 2 and +3. PL/I represents these 
numbers as follows: 



9 8 


+ 


3 



1 



1 



PL/I ignores the integers beyond the sign digit above, and produces the correct result 
01. In the following discussion, we show negative numbers with a leading - sign, with 
the assumption that the internal representation is in 10's-complement form. Thus, we 
write the number -2 as: 



There is no need to explicitly store the decimal position in memory, because the 
Compiler knows the precision and scale for each variable and constant. Before each 
arithmetic operation, the compiled code causes the necessary alignment of the operands. 
In later examples, we show a decimal point position to emphasize the effect of alignment. 

For example, the number —324.76 appears as: 



- 3 


2 4 


7 6 



When PL/I prepares this value for arithmetic processing, it first loads it into an 8- 
byte stack frame, consisting of 15 BCD digits with a high-order sign. In this case, the 
-324.76 is shown as: 























3 



2 4 



7 6 



In ordinary arithmetic, when beginning each operation you must properly align the 
operands for that operation and, upon completion, you must decide where the resulting 
decimal point appears. 

In PL/I, the Compiler performs the alignment and accounts for the decimal point 
position, but it is useful for you to imagine what is taking place, so you can avoid 
overflow or underflow conditions. In some cases, you might want to force a precision 
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or scale change during the computation using the DECIMAL or DIVIDE built-in 
functions. The sample programs discussed in the following sections give examples of 
these functions. 

15.3 Addition and Subtraction 

In PL/I, addition and subtraction are functionally equivalent. This is because in 
subtraction, PL/I first forms the 10's complement of the subtrahend and then performs 
the addition. Given two numbers x and y, with precision and scale (p,q) and (r,s), 
respectively, the addition operation proceeds as follows. 

First, PL/I loads the two operands onto the stack and then aligns them by shifting 
the operand with the smaller scale to the left until the decimal positions are the same. 
Given that the scale of x is greater than the scale of y, y is shifted q-s positions to the 
left, with zero values introduced in the least significant positions. 

After alignment, y has precision r+ (q — s) and scale q. PL/I signals a FIXED OVER- 
FLOW condition if significant digits are shifted into the sign position during the align- 
ment process. 

Here is a specific example. Suppose x = 31465.2437 and y = 9343.412 so that x 
has precision p = 9 and scale q = 4, while y has precision r = 7 and scale s = 3. 
Before alignment, the numbers appear as: 

|< p = 9 >\ 

< q = 4 > 
x = +000000314652437 

y= +000000009343412 

"I 
<s = 3> 

< r = 7 > 
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PL/I aligns y with x by shifting q-s = 4 — 3 = 1 positions to the left, producing: 



<- 



p = 9 > 

< q = 4 > 
x= +000000314652437 



y = +000000093434120 



< q > 

< r+(q-s) = 8 > 



The number of digits in the whole part of x is p-q, while the whole part of y contains 
r-s digits, 



< p-q = 5 > 
3 1465 
9343 
I <r-s = 4> 



so the sum must contain p-q = 5 digits in the whole part: 

3 1465 
+ 9343 



408 08 
< p-q = 5 > 



There is a possibility that some values could produce an overflow, requiring one 
extra digit in the whole part: 



99999 
+99999 



19999 8 
<(p-q) + l=6> 
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The total number of digits in the sum of x and y is the number of digits in the whole 
part, (p-q) + 1 = 6, plus the number of digits in the fraction, given by q, resulting in a 
precision of: 

(p-q) + l + q = p + 1 

Given two values x and y, of arbitrary precision and scale, you can use the specific 
case shown above to derive the form of the resulting precision and scale. First, the 
scale must be the greater of q and s, given by, 

max (q,s) 

and the resulting precision must have max(q,s) fractional digits. 

Second, the whole part of x contains p-q digits, while the whole part of y contains 
r-s digits. The result contains the larger of p-q and r-s digits, plus the fractional digits, 
along with one overflow digit, for a total of, 

max (p-q,r-s) + max (q,s) + 1 
digit positions. 
Because the precision cannot exceed 15 digits, the resulting precision must be, 

min(15,max(p-q,r-s) + max(q,s) + 1) 

digits. 

The precision and scale of the resulting addition or subtraction written as a pair 
(P',q') is: 



min(15,max(p-q,r-s) + max(q,s) + 1), max(q,s) 
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Using the preceding example: 

< p = 9 > 

<q = 4> 
x= +000000314652437 

y = +000000093434120 

< r + (q-s) = 8 > 
x+y= +000000408086557 

<-4-> 

< 10 > 

The precision (10,4) shown in the diagram is derived using the expression, 

p' ■ ■ q' . 



or: 



min(15,max(9-4,7-3) + max(4,3) + l), max(4,3) ) 



( min(15,max(5,4) + 4 + l), 4) = (min(15,10),4) = (10,4) 



15.4 Multiplication 

Evaluating the precision and scale for multiplication is simpler than addition and 
subtraction because PL/I does not have to align the decimal point before the multipli- 
cation. Given two operands x and y with precision and scale (p,q) and (r,s) respectively, 
PL/I multiplies the two operands digit by digit to produce the result. 
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Just as in ordinary hand calculations, the number of decimal places in the result is 
the sum of the scale factors q and s. The total number of digits in the result is the sum 
of the precisions of the two operands. To conform to the PL/I Subset G standard, 
PL/I includes one additional digit position in the final precision. The precision and scale 
of the result (p',q') is given by: 

P' q' 

(min(15,p + r + l),q + s) 

Suppose that x = 924.5 and y = 862.33, with the precision and scale values (4,1) 
and (5,2): 



x= +000000000009245 



+ 000000000086233 



The product of the digits of x and y is shown with the resulting precision and scale, 
x* y = +000000797224085 

<3 > 

< 10 > 

where PL/I computes the precision and scale as: 

(min(15,4 + 5 + l),l+2) = (min(15,10),3) = (10,3) 

PL/I signals the FIXEDOVERFLOW condition if the product contains more than 
15 significant digits. In the previous section, where x = 31465.2437 and y = 9343.412, 
the product x*y has precision 17, causing FIXEDOVERFLOW. 

In this particular case, you must apply the DECIMAL function to reduce the number 
of significant digits in either x or y. The computation is carried out as, 

DECIMAL(x,9,3) * y 
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which loads the stack with the two following values before the multiplication takes 
place: 



DECIMAL(x,9,3) = 

y = 



+00000031465 243 



+000000009343412 



The precision and scale of the product is: 
+293992729029116 



<r 



15 






PL/I first computes the precision asp + r+1 = 16, and then reduces this to the 
maximum 15 digit precision by: 

min(15,p + r+l) = min(15,16) = 15 

When performing multiplication, it is your responsibility to ensure that the precisions 
of the operands involved do not produce overflow. You can explicitly declare the 
precision and scale of the variables involved in the computation, or apply the DECIMAL 
function to reduce the precision of a temporary result. 

15.5 Division 

Division is the only one of the four basic arithmetic operations that can produce 
truncation errors. Therefore each division operation produces a maximum precision 
value consisting of 15 decimal digits, and a resulting scale that depends upon the scale 
values of the two operands. 

Assuming that x and y have precision and scale (p,q) and (r,s) respectively, and that 
x is to be divided by y, the division operation takes place as follows. 
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First, PL/I shifts x to the extreme left by introducing 15-p zero values on the right, 
leaving the dividend on the stack as: 



15-p 



<- 



-> 



x x 



xx . . 



PL/I then shifts the decimal point of x right by an amount s to properly align the 
decimal point in the result, producing the following operands: 



-> <- 



< q-s > <r 



15-p- 
15-p- 



^ 



-> 



X X 


. . XX 


00 


. .0 












V. 


r 


<s> 


00 . 


. 


yyy • 


•yy 



The significant digits of y then continuously divide the significant digits of x until 
the operation generates 15 decimal digits. 

In the diagram above, the number of fractional digits produced by the division is 
determined by the placement of the adjusted decimal point in x. The field following 
the decimal point contains (q-s) plus (15-p) positions, yielding the following precision 
and scale for the result of the division: 

(15, (q-s) + (15-p)) or (15,15-p + q-s) 

Suppose x = 31465.243, and y = 9343.41, have precision and scale values of (8,3) 
and (6,2), respectively. The value x when loaded on the stack appears as: 



<-3-> 

x = +000000031465243 
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PL/I then shifts the value of x to the extreme left and loads the value of y, producing 
the values: 

< 8 > <-15-8 = 7-> 



x= +314652430000000 
y = +00000000093434 1 



<2> 

6 > 



The imaginary decimal points are shifted to the right by two positions to properly 
align the decimal point in the result, producing: 



-> < — 7 



-> 



x= +314652430000000 
y =+ 00000000093434 1 

< 6—^| 

The six significant digits of y divide the significant digits of x, and the result is: 
= 15 5 



<-l+7 = 8^ 
x/y = +000000033676401 



In this case, the precision and scale of the result is given by: 

(15,(15-p + q-s) = (15,15-8 + 3-2) = (15,8) 

The most important consideration in decimal division is generating enough digits in 
the fractional part for the computation being performed. This is done in two ways. 

First, when aligning the dividend, PL/I pads with zeros and provides 15-p fractional 
digits. Thus, dividend values with small precision generate more fractional digits. 
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Second, if q is greater than s, then PL/I generates (q-s) additional fractional digits 
as shown above. If on the other hand, the dividend contains fewer fractional digits 
than the divisor, then q is less than s and (s-q) fractional digits are consumed. 

The case of q = s occurs quite often. In this particular situation, the number of 
fractional digits depends entirely upon the precision of the divisor, and results in 
15-p fractional digits. 

You might also want to truncate or extend the result with zeros using the DIVIDE 
built-in function during a particular computation (see the PL/I Language Reference 
Manual, Section 4.2.5). The form of the function is, 

DIVIDE (x,y,p,q) 

where p and q are literal constants. They can appear as an expression or subexpression 
in an arithmetic computation, and have the same effect as the statement: 

DECIMAL (x/y,p,q) 

As before, y divides x, but the precision and scale values are forced to (p,q). PL/I 
carries out the computation as described above, and then shifts the resulting value by 
the appropriate number of digits to obtain the desired precision and scale. 

End of Section 1 5 

References: Sections 3.1.2, 4.2 LRM 
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Commercial Processing 



Commercial applications of PL/I use decimal calculations. The four programs in this 
section illustrate PL/I built-in functions, EDIT formats including Picture, and the method 
of breaking down a complex program into small, logically distinct procedures. 



16.1 A Simple Loan Program 

Listing 16-1 shows the LOAN1 program that computes a loan payment schedule 
using three input values corresponding to the loan principal (P), the yearly interest rate 
(i), and monthly payment (PMT). LOAN1 continuously applies the following algorithm 
until the remaining principal reaches zero, and the loan is paid off. 

The algorithm is: 

1 . Each month, increase the starting principal P by an amount fixed by the interest 
rate. 

P = P + ( i * P) 

2. Each month, reduce the remaining principal by the payment amount. 
P=(P+(i*P))- PMT 

LOAN1 assumes that the principal does not exceed $999,999,999.99. Thus the 
declaration on line 12 defines P as a FIXED DECIMAL variable with precision 11 and 
scale 2. The payment does not exceed $9,999.99, so PMT is declared as FIXED DEC- 
IMAL with precision 6 and scale 2. Finally, LOAN1 defines the interest rate i as FIXED 
DECIMAL(4,2), allowing numbers as large as 99.99%. The two variables m and y 
correspond to the month and year, beginning at the first month of the first year. 

LOAN1 reads the initial values between lines 17 and 22. In this example, LOAN1 
does not perform any range checking. Thus it can accept negative values, and can 
process payment values that cannot pay off the loan. These checks would have to be 
made in a real application environment. 
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On each iteration, LOAN1 increases the month until it reaches the 12th month, at 
which point the built-in MOD function, line 26, increments the year. LOAN1 then 
displays the current principal P on line 32, and adds the monthly interest on the 
following line, 

LOAN1 performs the computation on line 33. The variable i has precision and scale 
4(2), while the variable P has precision and scale 11(2). Therefore, the multiplication i 
*P yields a temporary result with precision and scale, 15(4). 

Next the division by the literal constant 1200 is required because the interest rate is 
expressed as a percentage (division by 100) over a one-year period (division by 12). The 
result of the division (i * P)/1200 has precision 15, because the constant 1200 has 
precision and scale, 4(0). PL/I computes precision and scale in division as (15,15-15+ 
4-0). Finally, LOAN1 uses the built-in function ROUND to round the second decimal 
place, the cents position. 

In the last month, if the remaining principal is less than the payment, LOAN1 
performs the test on line 34. If the test is true, line 35 changes the payment to equal 
the principal. Line 36 prints the payment, and finally, line 37 reduces the principal by 
the payment using the assignment statement: 

P = P - PMT 

Listing 16-2 shows the output from LOAN1 using an initial loan of $500, interest 
rate of 14%, and payment of $22.10 per month. 
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.8 c 



9 
10 
11 
12 
13 
14 
15 
IB 
17 
1 

19 c 

20 c 

21 c 

22 c 

23 c 

24 c 

25 d 

26 d 

27 e 

28 e 

29 e 

30 e 

31 d 

32 d 
33 
34 
35 
3G 
37 
38 
39 



40 b 

41 b 



/ft**************************************************-****/ 
/* This program produces a schedule of loan payments */ 
/* usins the following algorithm: if P = loan payment* */ 
/* i = interest* and PliT is the monthly payment then */ 
/* P = (P + (i*P) - PMT) . */ 

/**#*###*###*******#****#**###****##*****###****#*##**#*/ 
loanl : 

procedure options(main) i 

declare 

m fixed binary* 

y fixed binary* 

P fixed decimal ( 11 »2) » 

PMT fixed decimal (G» 2) t 

i fixed decimal (4 >2) i 



i — do while('l'b); 

put s Kip listPPrincipal ')! 

Set list (P) ! 

put 1 i st ( * In te rest ' ) i 

Set list ( i ) 5 

put 1 i s t ( v Payment ' ) i 

Set list(PMT) ! 

m = Oi 

y = 0! 

do while (P > 0)5 

if Mod (m »12) = then 
do i 

y = y + 1 i 

put skip 1 i st ( x Year ' *y ) i 
end i 
m = m + 1 i 
put skip list(m*P>; 
P = P + roundt i * P / 1200 * 2) 5 
if P < PMT 

then PMT = Pi 
put list(PMT) ! 
P = P - PMT! 
1 — end 5 
end ! 



' — end loanl! 



Listing 16-1. The LOAN1 Program 
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A>loanl 






Principal 500 






Interest IQ 






Payment 22,10 






Year 1 






1 


500.00 


22.10 


2 


483,73 


22,10 


3 


467.27 


22.10 


a 


450, G2 


22.10 


5 


433.78 


22.10 


B 


416,74 


22.10 


7 


399.50 


22.10 


8 


382,06 


22,10 


9 


364,42 


22.10 


10 


346,57 


22.10 


11 


328,51 


22.10 


12 


310.24 


22.10 


Year 2 






13 


291.76 


22. 10 


14 


273,06 


22.10 


15 


254.15 


22.10 


16 


235,02 


22.10 


17 


215.66 


22.10 


18 


196.08 


22.10 


19 


176.27 


22.10 


20 


156.23 


22.10 


21 


135,95 


22.. 10 


22 


115,44 


22.10 


23 


94.69 


22.10 


24 


73,69 


22,10 


Year 3 






25 


52,45 


22.10 


2G 


30,96 


22,10 


27 


9.22 


22,10 


Principal "C 






A> 







Listing 16-2. Output from the LOAN1 Program 
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16.2 Ordinary Annuity 

Listing 16-3 shows the ANNUITY program. Given the interest rate (i) and two of 
three values, ANNUITY computes either the present value (PV), the payment (PMT), 
or the number of pay periods (n) for an ordinary annuity. 

ANNUITY contains one main loop between lines 35 and 80 which reads the present 
value, payment, and yearly interest from the console. On each iteration, you enter two 
nonzero values and one zero value, then ANNUITY computes the value of the variable 
that you enter as zero. ANNUITY retains the values on each loop so that you can 
enter a comma if you do not want to change the value. In this example, ANNUITY 
does not check that the input values are in the proper range. 



7 


r 
b 


8 


b 


9 


b 


10 


b 


11 


b 


12 


b 


13 


b 


14 


b 


15 


b 


IB 


b 


17 


b 


18 


h 


19 


b 


20 


b 


21 


b 


22 


b 


23 


b 


24 


b 


25 


b 


26 


b 


27 


b 


28 


b 


29 


c 


30 


c 


31 


c 


32 


c 


33 


b 



/* This program computes either the present value ( PV) * #/ 
/* the payment ( PMT) > or the number of periods in an */ 
/♦ordinary annuity. */ 

/***####*■######**####*#*#*#*#**##**####****######**#*#**/ 
annui ty : 

procedure options(main)! 

1 replace 

clear by x ''' i 



true 
declare 
PMT 
PV 
IP 
x 
y i 



by M 'bi 

fixed decimal(7>2)» 

fixed dec imal (9 >2) t 

fixed decimal(6»B)» 

float binary > 

float binary) 

float binary » 
fixed? 



declare 

ftc entryffloat binary(24)) 

retums(oharacter(17) varying) ? 



put list (clear 
put 5kip(2> list 
( VA iEnter Known Values* or 



INORDINARY ANNUITY') 
0» on Each Iteration')? 



on error 
beSin i 

put sKip 1 ist ( v " i Inval i d Data* Re-enter') 
Soto ret ry i 
1 — end ! 



Listing 16-3. The ANNUITY Program 
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34 


b 


35 


c 


36 


c 


37 


c 


38 


c 


39 


c 


40 


c 


41 


c 


42 


c 


43 


c 


44 


c 


45 


c 


46 


c 


47 


c 


48 


c 


49 


c 


50 


c 


51 


c 


52 


c 


53 


c 


54 


d 


55 


d 


56 


d 


57 


d 


58 


c 


59 


c 


60 


c 


61 


c 


62 


c 


63 


d 


64 


d 


65 


d 


66 


d 


67 


d 


68 


c 


69 


c 


70 


c 


71 


c 


72 


c 


73 


d 


74 


d 


75 


d 


76 


d 


77 


d 


78 


d 


79 


d 


80 


c 


81 


b 


82 


b 



iPresent Value ' ) 5 
') ; 
') 5 

') 5 



ret ry : 

do while ( t rue > 5 

put skip<3) 1 i st ( 

set list(PV)! 

put list('*iPaywent 

Set list(PMT)! 

put 1 ist ( XA i Interest Rate 

Set 1 ist ( y i ) 5 

i =. vi / 1200! 

put list(' A iPay Periods 

Set list(n) 5 

if PV = ! PMT = then 
x = 1 - l/( 1 + i )*/n i 



/* compute the present value */ 

if PU = then 
do i 

PV = PMT * dec(ftc(x/i) ,15.6) 5 
put edi t ( <A iPresent Malue is '»PV) 
(a»p*$$$»$$*»$**V,99') 5 
end ! 

/* compute the payment */ 
if PMT = then 



do 



PMT = PV # dec(ftc(i/x) »15t8> i 
put edit ( x * iPayment is '»PMT) 
(a»p**$ > *$$»$$$V,99') 5 



1 — end ! 

/* compute number of periods */ 

if n = then 
do 5 

IP = ftc(i) 5 

x = char(PV * IP / PMT) 5 
n = ceil ( - loS( l-x)/loS(l+i ) )5 
put edit ( * A i ' »n > ' Pay Periods') 
( a »p v ZZZ9' >a) 5 
1 — end 5 



end 5 



end annuity i 
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Listing 16-4 shows an interaction with the ANNUITY program in which several 
different values are used as input. 

A> annuity 

ORDINARY ANNUITY 

Enter Known Values* or 0> on Each Iteration 



Present Value 3Z000 
Pa/went 
Interest Rate 8,75 
Pay Periods 360 
Payment is $251.74 

Present Value > 
Payment 
Interest Rate / 
Pay Periods 2Q0 
Payment is *282,78 

Present Value 

Payment > 

Interest Rate / 

Pay Periods / 

Present Value is $31 t998.87 

Present Value 32000 
Payment t 
Interest Rate t 
Pay Periods 
240 Pay Periods 

Present Value "C 
A> 

Listing 16-4. Interaction with the ANNUITY Program 

16.2.1 Mixed Data Types 

ANNUITY uses both FLOAT BINARY and FIXED DECIMAL data because it must 
perform a mixture of decimal arithmetic calculations and analytic function evaluations. 
The variables used throughout the program are defined between lines 12 and 18 as 
follows: 

■ PMT holds the payment value, is declared as FIXED DECIMAL(7,2), and can 
be as large as $99,999.99. 
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■ PV holds the present value, is declared as FIXED DECIMAL(9,2), and can be 
as large as $99,999,999.99. 

■ The variable IP holds the interest rate for a one month period, and is declared 
as FIXED DECIMAL with six decimal places. 

■ The variable n holds the number of payment periods, is declared as FIXED 
BINARY, and can range from 1 to 32767. 

■ The variables x, yi, and i are FLOAT BINARY numbers used during the com- 
putations to approximate decimal numbers with 7 decimal places. 

ANNUITY computes the unknown value using the equations shown below, rather 
than the iteration. ANNUITY assumes the interest rate is greater than zero. 

First, the present value is given by: 

1 



1 
PV = PMT 



(1 + i) n (1) 



Transposing equation (1) gives: 
PMT = PV 



1 

(1 +i)" (2) 



Finally, solving for n gives: 



l 
Log ( 1 - PV ( - ) ) 
PMT 

n = (3) 

Log ( 1 + i ) 

The following expression appears in both equations (1) and (2): 

1 - 1/(1 + i) ** n 
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Therefore, ANNUITY stores this value in the variable x, line 47, and uses it when 
evaluating PV and PMT. x is only an approximation of the decimal value given 
by this expression. 

16.2.2 Evaluating the Present Value PV 

If you enter a zero value for PV, then ANNUITY executes the DO-group between 
lines 53 and 57, and computes PV as: 

PU = PMT * dec(ftc(x/i)#15*6); 



Line 20 declares ftc as an external subroutine. It is part of the PL/I Run-time Sub- 
routine Library (RSL), so ANNUITY only needs to declare it as an entry constant to 
use it. 

The division x/i produces a FLOAT BINARY temporary result that ftc then converts 
from FLOAT to CHARACTER form. For example, suppose that x/i produces the value 
3.042455E + 01. Then ftc(x/i) returns 30.42455 which is acceptable for conversion to 
decimal. If PL/I cannot convert the floating-point argument to a 15-digit decimal num- 
ber, ftc signals the ERROR(l) condition, indicating a conversion error. 

Finally, the built-in DECIMAL function is applied to the character string to convert it 
to a specific precision and scale, 15(6). When this is done, the multiplication and 
subsequent assignment to PMT takes place. 

How is this particular value for precision and scale decided? To answer the question, 
first consider a restricted form of the same program, 

declare 

PMT fixed decimal(7»2)» 

PV fixed decimal (9 *2) » 

fixed d e c i w a 1 ( u t v ) 5 
py = PMT * 5 

where you must decide on the appropriate constant values for u and v. 

PV has precision and scale 9(2), and thus there must be seven digits in the whole part 
and two digits in the fraction. PL/I generates the full seven digits in the whole part if the 
product PMT * Q results in any of the precision and scale values: 

(9,2) (10,3) (11,4) (12,5) (13,6) (14,7) (15,8) 
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The assignment to PV truncates any fractional digits beyond the second decimal place. 
Because PMT has precision and scale (7,2), you can choose Q with a precision and scale 
of (15,6). Then the multiplication produces a result with precision and scale, 

(min(15,7 + 15 + l),2 + 6) = (15,8) 

according to the rules stated previously. 

Given an expression with precision and scale values as shown below, 

a = b * c 
' (p,q) (r,s) (u,v) 

where p, q, r, and s are constants, you can set the precision and scale of c to: 

u = 15 v = 15 — (p + q — s) 

Thus, using the values shown in the original program, the precision and scale of Q 
becomes: 

v = 15 - (9 + 2 - 2) = 8, or (u,v) = (15,6) 

16.2.3 Evaluating the Payment PMT 

If you enter a nonzero present value for PV and a zero value for the payment PMT, 
then ANNUITY enters the DO-group beginning at line 63 and computes the value of 
PMT as: 

PMT = PV * dec <ftc(i/x)*15»8)» 

The computation uses essentially the same technique as shown in the previous exam- 
ple. You must decide the precision and scale of the second operand in the multiplication. 
You are really concerned only with the value of the scale because the precision can be 
taken as 15. 

Using the analysis shown above, evaluate the form, 

a = b * c 

(7,2) (9,2) (15,v) 
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and determine the value for v: 

v = 15 - (p + q - s) = 15 -(7 + 2 - 2) = 8 

16.2.4 Evaluating the Number of Periods n 

When you enter nonzero values for PV and PMT, but set the number of periods to 
zero, ANNUITY executes the DO-group beginning on line 73 to compute n. The 
assignment on line 74 first changes the interest for a monthly period from FLOAT 
BINARY to FIXED DECIMAL. 

Next, the assignment on line 75, 

x = char(PV * IP / PMT) 5 

first computes the partial decimal result PV * IP / PMT, then converts the result to 
CHARACTER, and then to FLOAT BINARY through the assignment to x. 

The multiplication PV * IP produces a temporary result with the precision and scale: 

PV * IP 

(9,2) (7,2) 



(15,4) 

The temporary result is now divided by PMT and results in another temporary result 
with the following precision and scale, 

PV*IP / PMT 

(15,4) (7,2) 



(15,2) 
because, according to the rules for division, 

(15,15-p + q-s) = (15,15-15 + 4-2) = (15,2) 
thus providing two decimal places in the computation. 
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The intermediate conversion to CHARACTER form is necessary because otherwise 
PL/I would first convert the intermediate result to FIXED BINARY, and then to FLOAT 
BINARY, resulting in truncation of the fraction. This sequence of conversions is nec- 
essary to maintain compatibility with the full language. 

If required, you could generate additional fractional digits by applying the DECIMAL 
built-in function following the multiplication, 

x = char( dec( PV*P, 11,4 ) / PMT); 

and produce a quotient with precision and scale: 

(15,15-11+4-2) = (15,6) 

ANNUITY uses the value x in the expression on line 76 to compute the number of 
payment periods, and applies the CEIL function to the result so that any partial month 
is treated as a full month in the payment period analysis. 

Finally, ANNUITY uses the Picture edit format to write out the values of PV, PMT 
and n. 

16.3 Loan Payment Schedule Format 

The LOAN2 program shown in Listing 16-5 is essentially the same as that presented 
in Section 16.1, but it has a more elaborate analysis and display format. LOAN2 uses 
an algorithm similar to that described in Section 16.1. The main processing occurs 
between lines 101 and 136, where the program increases the initial principal by the 
monthly interest, and reduces it by the monthly payment until the principal becomes 
zero. 

The four listings that follow the discussion of the program show several examples 
of interaction with LOAN2. 

Listing 16-6 shows a minimal display corresponding to a loan of $3000 at a 14% 
interest rate with a payment of $144.03. Assume an inflation rate of 0% with a starting 
payment on 11/80, and end-of-year taxes due in December. 

The display shows the principal, interest in December, monthly payment, amount 
paid toward principal in December, and amount of interest paid in the last month of 
the fiscal year. 
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Listing 16-7 shows another execution using the same values as the first time, but 
using a display level of 1 . The output also contains the yearly interest paid on the loan 
for each fiscal year that would be deducted from the taxable income. 

Listing 16-8 uses the same initial values of the previous examples, but provides a 
full display of the monthly principal, interest, monthly payment, payment applied to 
the principal, and interest payment. 

Listing 16-9 also shows the same loan and interest rate with an adjustment in dollar 
value due to inflation. This example assumes the inflation rate of 10%, so that all 
amounts are scaled to the value of the dollar at the time the loan is issued. 

For tax reporting, the display showing the total interest paid at the end of each year 
is not scaled, and thus does not match the sum of the interest paid during the year. If 
we assume a 0% inflation rate, the total loan payment is 3,456.97, taken from the 
previous output. 

But if we assume an inflation rate of 10%, the total cost of the loan in dollars today 
is, 

2,457.00 
+ 374.25 



2,831.25 

resulting in a net gain of 68.75 over a two year period! 

1 a /******##*********#********#******************#******#/ 

2 a /* This program computes a schedule of loan payments */ 
3a /* usinS an elaborate analysis and display format. */ 
4a /* It contains five internal procedures: DISPLAY* */ 
5a /* SUMMARY. CURRENT-YEAR » HEADER, and LINE. */ 
G a /*****#*********#*************#**#*****************#**/ 

7 a loan2: 

8 b procedure opt i ons ( main ) 5 

9 b Xreplace 

10 b t rue by M v b t 

11 b false by ^0 x b , 
12b clear by v *z K 5 



13 b 



Listing 16-5. The LOAN2 Program 
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14 


b 


15 


b 


IB 


b 


17 


b 


18 


b 


13 


b 


20 


b 


21 


b 


22 


b 


23 


b 


24 


b 


25 


b 


2G 


b 


27 


b 


28 


b 


29 


b 


30 


b 


31 


b 


32 


b 


33 


b 


34 


b 


35 


b 


36 


b 


37 


b 


38 


b 


38 


b 


40 


b 


41 


b 


42 


b 


43 


b 


44 


b 


45 


c 


46 


c 


47 


c 


48 


c 


43 


b 


50 


b 


51 


b 


52 


b 


53 


b 


54 


b 


55 


b 


56 


b 


57 


b 



eclare 








end 


bitd 


. 




M 


fixed 


binary > 




SM 


fixed 


binary > 




Y 


fixed 


binary > 




SY 


fixed 


binary > 




fm 


fixed 


binary > 




dl 


fixed 


binary > 




P 


fixed 


dec 


Mai 


10.2) , 


PV 


fixed 


dec 


«al 


10*2) i 


PP 


fixed 


dec 


Mai 


10.2) . 


PL 


fixed 


dec 


Mai 


10.2) » 


PMT 


fixed 


dec 


Mai 


10.2) i 


PMV 


fixed 


dec 


Mai 


10.2) . 


INT 


fixed 


dec 


Mai 


10.2) . 


YIN 


fixed 


dec 


Mai 


10.2) . 


IP 


fixed 


dec 


Mai 


10.2) . 


y i 


fixed 


dec 


Mai 


4.2) » 


i 


fixed 


dec 


Mai 


4.2) . 


INF 


fixed 


dec 


Mai 


4.3) . 


ci 


fixed 


dec 


iMal 


15.14) . 


f i 


fixed 


dec 


Mai 


7.5) . 


i r 


fixed 


dec 


Mai 


4.2) ! 



declare 

name characte r ( 14) varying static initial ( 'Scon ') » 
output file? 



put lisUclear »' A i A iS U M M A R Y 



F 



PAYMENTS'); 



on undefinedf i le (output ) 
— be sin 5 

put skip 1 ist ( ' " i * icannot write to'.name)! 

30 to open_output 5 
1 — end 5 

open_outPut : 

put sKip(2) 1 ist ( ' "i^iOutPut File Name ')i 

Set list (name ) i 

if name = 'Scon' then 

open file(output) t itle ( 'Scon ' ) print paSesize(O)! 
else 

open file(output) title (name ) print! 



Listing 16-5. (continued) 
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58 


b 


on error 




59 


c r— besin i 




BO 


c 




=>ut skip 1 i st ( ' " i " iBad Input Data» Retry')? 


61 


c 




Soto retry! 




62 


c 


— en 


i\ 




63 


b 






64 


b 


1 — retry: 






65 


c 


do whi 


. e ( t rue ) 5 




66 


c 


put 


skip(2) 1 ist ( * " i "Princ ipal 


') i 


67 


c 


Set 


list(PV) ; 




68 


c 


P = 


PVi 




69 


c 


put 


list(*"i"ilnterest ')! 




70 


c 


Set 


1 ist ( y i ) i 




71 


c 


i = 


y i i 




72 


c 


put 


1 i s t ( ' " i " i P a y w e n t ' ) 5 




73 


c 


Set 


list(PMV) i 




7 a 


c 


PMT 


= PMV! 




75 


c 


put 


1 i s t ( x " i " i 1 1 n f 1 a t i o n 5 ) ! 




76 


c 


Set 


1 i st ( i r ) i 




77 


c 


f i 


= 1 + ir/ 1200 5 




78 


c 


ci 


= 1 .00 5 




79 


c 


put 


1 i s t ( ' '" i " i S t a r t i n S Month ' ) ! 




80 


c 


Set 


1 i s t ( s m ) 5 




81 


c 


put 


1 ist ( v * i " iStart ins Year ')5 




82 


c 


Set 


1 i st ( sy ) i 




83 


c 


put 


1 i s t ( '" i " i F i s c a 1 Month ')! 




84 


c 


Set 


list (fw) 5 




85 


c 


put 


e d i t O " i " i D i s p 1 a y Level ' > 




86 


c 




w i"iYr Results : ' » 




87 


c 




'" i " i Y r Interest: 1 ' > 




88 


c 




w i"iAll Values : 2 ') 




89 


c 




( s k i p > a ) ! 




90 


c 


Set 


list(dl) ; 




91 


c 


if 


il < 0! dl > 2 then 




92 


c 




;i Snal error! 




93 


c 


m = 


Sffl i 




94 


c 


Y = 


sy i 




95 


c 


IP 


= 0! 




96 


c 


PP 


= 0! 




97 


c 


YIN 


= 05 




98 


c 


if name "= w then 




as 


c 


put file(output) p a S e 5 




100 


c 




call header()i 
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101 


d 




— do u 


hi 


le (P > 0) ; 


102 


d 




en c 


= false! 


103 


d 




INI 


= round ( i * P / 1200. 2 ) 5 


104 


d 




IP 


= IP + INT! 


105 


d 




PL 


' = Pi 


106 


d 




P 


= P + INT! 


107 


d 




if 


P < PMT then 


108 


d 






PMT = Pi 


109 


d 




P 


= P - PMTi 


110 


d 




PP 


= PP + (PL - P) i 


111 


d 




INF 


= c i i 


112 


d 




ci 


= ci / f i i 


113 


d 




if 


P = ! dl > 1 ! m = fm then 


114 


e 








do i 


115 


e 








put file (output ) sKip 


116 


e 








edit ( ' ! ' (100*m+y ) ( a .p x 99/99 ' ) i 


117 


e 








call display(PL * INF. INT * INF. 


118 


e 








PMT * INF. PP * INF. IP * INF) i 


119 


e 






- 


end 5 


120 


d 




if 


m = fm & dl > then 


121 


d 






call summary ( ) 5 


122 


d 




m = 


m + 1 i 


123 


d 




if 


w > 12 then 


124 


e 








do 1 


125 


e 








m = 1 ; 


126 


e 








y = y + 1 i 


127 


e 








if y > 99 then 


128 


e 








y = 0! 


129 


e 








end 5 


130 


d 




— end i 




131 


c 




.- if dl 


= then 


132 


c 




call line()» 


133 


c 




— else 




134 


c 


if A er 


d then 


135 


c 


call summary ( ) 5 


136 


c 


— e 


nd ret 


rv 


i 
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137 


b 


138 


b 


139 


b 


140 


b 


141 


b 


142 


b 


143 


c 


144 


c 


145 


c 


14G 


c 


147 


c 


148 


c 


149 


c 


150 


c 


151 


c 


152 


b 


153 


b 


154 


b 


155 


b 


15G 


b 


157 


b 


158 


c 


159 


c 


1G0 


c 


161 


c 


162 


c 


163 


b 


164 


b 


165 


b 


166 


b 


167 


b 


168 


b 


169 


c 


170 


c 


171 


c 


172 


c 


173 


c 


174 


c 


175 


c 


176 


c 


177 


c 


178 


c 


179 


c 


180 


c 


181 


c 


182 


b 



/**♦*#*********##**#************♦#********#**********/ 
/* This procedure performs the output of the actual */ 
/* parameters passed to it by the main part of the •*/ 
/* program. */ 

/♦a**************************************************/ 
display : 

procedure ( a »b »c »d *e ) 5 

declare 

(a»b>ctdte) fixed decimal ( 10 >2) i 

put file (output) edit 

( ( I ' »a t v ! ' »b » v ! ' ic i 1 I ' id »' ! ' te i 1 ! ' ) 

(a»2(2(p**zz»zzz>zz9v.99' »a) t 
p % $zzz >zz9,u99' »a> ) ! 
end display 5 

/* This procedure computes the summary of yearly */ 
/* interest. */ 

/**********#*************♦*#*♦**#*****************/ 
summary : 

procedure 5 

end = true? 

call current_y ear( IP-YIN) ; 

YIN = IP! 
end summary » 

/* This procedure computes the interest paid durinS */ 
/* cu rrent year. */ 

cu r rent_y ear : 
procedure (1)5 
declare 

yp fixed binary* 
I fixed decimal ( 10 >2) 5 
y p = y ! 

if fm < 12 then 
yp = yp - 1 i 
callline()i 
put skip file(output) edit 

( * ! ' > v Inte rest Paid During ' w »yp » * - * w »y » ' is 'ili s \') 
(a»x(15)»2(a»p*99') »a »p * *$*»$$* »*$9V. 99 ' »x(16) »a) 5 
call 1 ine ( ) 5 
end current year! 



Listing 16-5. (continued) 



213 



16.3 Loan Payment Schedule Format 



PL/I Programming Guide 



183 b 

184 b 

185 b 

186 b 

187 b 

188 o 

189 c 

190 c 

191 c 

192 c 
193 
194 
195 
19B 
197 
198 

199 c 

200 c 

201 c 

202 c 

203 c 

204 b 

205 b 

206 b 

207 b 

208 b 

209 c 

210 c 

211 c 

212 c 

213 c 

214 c 

215 c 

216 b 

217 b 

218 b 



/* This procedure defines and prints out an elaborate */ 
/* header format. */ 

heade r: 

procedure 5 

put file(output) list (clear) 5 

call 1 ine ( ) 5 

put file(output) sKiP edit 

O ! ' , V L A N PAYMENT BUMMARY't'i' 

<a»x<19> ) 5 
call 1 ine ( ) 5 
put file(output) skip edit 

( v ! ' i x Inte res t Rate ' >yi »'%'» x Inflation Rate'fir>'X 

(a >x( 15) »2(a»p x b99u,99' »a »x(6) ) tx(9) »a) i 
call 1 ine ( ) i 

put file(output) sKip edit 
("IDate !'»' Principal !'»'Plus Interest!'*' Pavm 

'Principal Paid !'» v Inte rest Paid !') (a)! 
call line()5 
end header! 



'»'!') 



ent ! ' » 



/* Th 

/**** 

line: 

pr 

de 



is procedure prints out a series of dashed lines. */ 



•ocedure 5 
>clare 
i fixed bin ; 
put file(output) sKip edit 

r ' ,» ' , 

p ' do i = 1 to 4)) (a)i 

end 1 ine 5 



end loan25 



Listing 16-5. (continued) 
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16.3.1 Variable Declarations 

Starting on line 14, LOAN2 declares several data items: 

■ PV present value, initial principal 

■ yi yearly interest rate 

■ PMV monthly payment 

■ ir yearly inflation rate 

■ sm starting month of payment (1-12) 

■ sy starting year of payment (0-99) 

■ fm fiscal month, end of fiscal year (1-12) 

■ dl display level (0-2) 

LOAN2 declares the initial principal and payment variables as FIXED DECIMAL 
(10,2), allowing values as large as $99,999,999.99. 

It also allows the yearly interest rate and yearly inflation rate to be as large as 99.99. 

The month and year variables, sm, sy, and fm are FIXED BINARY and LOAN2 
assumes that these variables properly represent month and year values. 

The variable dl is the display level and defines the amount of information LOAN2 
displays during a particular iteration of the program. That is, produces an abbreviated 
display, 1 produces additional information, and 2 gives the full trace. 

LOAN2 also declares several other variables used throughout the program: 

■ P initially set to PV, but changes during execution 

■ PP total principal paid 

■ PL principal for current line, holds P for display purposes 

■ PMT payment initially set to PMV; changes during execution 

■ INT computed interest during current month 

■ YIN interest at beginning of current year 

■ IP total interest paid 

■ i interest rate, initialized to yi 

■ INF percent devaluation of original dollar due to inflation 

■ ci current devaluation due to inflation 

■ fi factor for computing current inflation 

P and PMT are working variables for the principal and payment, so that the program 
does not destroy the original variables PV and PMV during the computations. If you 
enter a comma for subsequent input requests, LOAN2 retains the previous value. 
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16.3.2 Program Execution 

The program execution begins on line 42 with a clear screen character for the Lear- 
Siegler ADM-3A CRT. This control character is defined in the % REPLACE statement 
on line 12. If you are not using an ADM-3A, you can substitute the proper character 
and recompile the program. 

LOAN2 sets an ON-condition to trap possible errors in the OPEN statement, lines 
54 to 56, and then prompts for the report output filename. LOAN2 initializes the 
variable name to the value $con, and if you enter a comma rather than a file or device 
name, LOAN2 assumes the console as the output device. 

If you enter either a comma or the name $con as the output filename, then the OPEN 
statement, line 54, opens the console with a zero page size. This means that the run- 
time system does not issue any form-feeds at the end of each logical page. Otherwise, 
LOAN2 opens the output file or device as a normal PRINT file so that the run-time 
system places form-feeds into the output file or sends them to the physical output 
device, usually the printer, denoted by $lst. 

The ON condition set at line 58 traps any occurrence of the ERROR condition, 
including ERROR(l), which indicates a data conversion error. LOAN2 also program- 
matically signals invalid data on line 92 if the value of dl is out of range. 

LOAN2 does not contain a complete set of routines for error checking. To make 
the program commercially functional, it should signal errors for all other invalid input 
data items, such as a negative interest rate. Furthermore, out-of-bounds computations 
should signal a FIXED OVERFLOW condition. 

Beginning on line 67, LOAN2 reads a set of input values, and then initializes the 
variables for each set of input values beginning on line 93. The PUT LIST statement 
on line 99 executes a page eject if the output file is not the console. Line 100 then 
prints a page header by calling the HEADER subroutine. You should compare the 
formatting statements in the header subroutine with the output values shown in the 
output listings. 

The main processing takes place in the DO-group beginning at line 101, that executes 
repeatedly until the principal is reduced to zero. The variable end indicates whether 
an end-of-year summary has been printed, line 159, and thus avoids the possibility of 
printing a duplicate summary, line 134. 
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On lines 103 and 104, LOAN2 computes the monthly interest INT for the current 
principal P and sums it in IP. LOAN2 saves the current principal for later display in 
PL, and then adds the monthly interest to the principal. If the payment exceeds the 
remaining principal on line 107, LOAN2 reduces the payment to cover this remainder. 
It then reduces the principal by the payment amount, eventually producing a zero value 
if the original payment is sufficient to pay off the loan. Then on lines 111 and 112 
LOAN2 sums the total principal paid and computes the inflation rate. 

16.3.3 Display Formats 

The decision logic for displaying the current computation is somewhat complicated 
because LOAN2 has three display formats. If it is the last iteration, the principal P is 
zero, you select the full display format, dl > 1, or the current month is the end of the 
fiscal year, m = fm, then LOAN2 writes the current computation between lines 114 
and 118. 

The Picture format p'99/99' displays the month and year, where 100*m + y produces 
a four-digit number to match this format. For example, if m = 11 and y = 64, then, 

100 * m + y = 100 * 11 + 64 = 1164 

1164 appears as 11/64, when printed using the given Picture format. 

The DISPLAY subroutine actually performs the output function, based upon the six 
actual parameters listed in the CALL statement on line 117. The main program first 
adjusts each argument, by the current inflation rate INF, and then passes it to DISPLAY. 
If the inflation rate is set to 0%, the value of INF is 1.00 at this point in the computation. 

The body of the display subroutine, listed between lines 142 and 151 could be 
included in the line subroutine because there is only one call to display. However, 
display illustrates FIXED DECIMAL parameter passing mechanisms and serves to break 
the program into smaller, more readable, segments. Again, you should compare the 
format specifications in the display subroutine with the actual program output. 

The statement on line 120 then checks for the end of fiscal year, m = fm, and, if 
the display mode is either 1 or 2, LOAN2 prints a yearly interest summary using the 
summary subroutine. Summary in turn, calls the current_year subroutine to write the 
yearly interest paid, IP- YIN. The assignment on line 161 retains the base value for the 
next year's display in YIN. 
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If the fiscal year does not end in December, fm< 12, current_year splits the interest 
rate payment between two calendar years, yp = y - 1. Again, you could combine 
current_year with the summary subroutine without changing the overall program logic. 

The end of the main loop, between lines 131 and 136, contains statements that 
finalize the report. If you select the abbreviated display format, dl = 0, the CALL 
statement on line 132 invokes LINE and prints a line of dashes to complete the display. 
Otherwise, LOAN2 checks to ensure there have been intervening output lines ( end). If 
there have been, it prints an interest summary on line 130. Finally, control returns to the 
top of the DO-group, and LOAN2 reads additional input parameters. 

b>laan2 
403 

404 SUMMARY OF PAYMENTS 
405 

400 Output File Name , 

401 Principal 3000 
002 Interest 14 

403 Payment 144,03 

404 ^Inflation 

405 Starting Month 11 
40G Starting Year 80 
407 Fiscal Month 12 
408 

409 Display Leuel 

410 Yr Results : 

411 Yr Interest : 1 

412 All Values : 2 
413 

414 

415 

41G ! LOAN PAYMENT SUMMARY 1 

417 

418 ! Interest Rate 14.002 Inflation Rate 00.001 ! 

419 

420 IDate (Principal IPlus I nte res t ! Payment (Principal Pai d ! Int e res t Paid! 

421 

422 ! 12/B0I* 2.890.971* 33.731* 144.031$ 219.331$ 68.73! 

423 112/81!$ 1.479.021$ 17.261$ 144.031$ 1.647.751$ 368.67! 

424 111/821$ 0.251$ 0.00!$ 0.251$ 3.000.001$ 456.97! 



425 



Listing 16-6. First Interaction with LOAN2 
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Output File Name 
Principal 
Inte rest 
Payment 
II nf 1 at ion 
Starting Month 
Starting Year 
Fiscal Month 



Display Leuel 
Yr Results : 
Yr Interest: 1 
All Values : 2 1 







LOAN 


P A Y M 


E N T S U 


M 


MARY 








Interest Rate 


14.00* 


Inflation 


Rate OO.OOZ 




! Date 


P 


rincipal IPlus Interest 


Payment [Principal Pai d ! In te rest Paid! 


! 12/80 


$ 


2.890.971$ 


33.73 


$ 144.031$ 




219.331$ 


88.73! 






Interest Paid 


Du rin 3 


80- v B0 is 




$68.73 




1 12/81 




1 ,1379.021$ 


17.28 


$ 144.031$ 




1 »B47.751$ 


368.87 1 






Interest Paid 


During 


81 - x 81 is 




$299.94 




! 11/82 


$ 


0.25!$ 


0.00 


$ 0.25!$ 




3 ,000.00!$ 


456.97 1 






Interest Paid 


Du r in 3 


82-*82 is 




$88.30 





Listing 16-7. Second Interaction with LOAN2 
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Output File Name 
Principal 
Inte rest 
Payment 
Zlnfl ati on 
Starting Month 
Starting Year 
Fiscal Mon th 



Display Level 
Yr Results : 
Yr Interest: 1 
All Values : 2 



LOAN PAYMENT SUMMARY 



! Interest Rate 14.00Z Inflation Rate O0.0OZ ! 

IDate ! Principal IPlus Interest ! Payment iPrincipal Paid! Interest Paid! 



11/801$ 3.000.00!$ 
12/80!$ 2.830.971$ 



35.00 !$ 144.03!$ 
33,73 !$ 144.03!$ 



109.03!$ 
219.33!$ 



35.00! 
G8.73! 



Interest Paid DurinS 'BO-'BO is 



$68.73 



01/81 


$ 


2. 


02/81 


$ 


2, 


03/81 


$ 


2. 


04/81 


$ 


2. 


05/81 


$ 


2, 


06/81 


$ 


2. 


07/81 


$ 


2. 


08/81 


$ 


1 . 


09/81 


$ 


1 , 


10/81 


$ 


1 . 


11/81 


$ 


1 . 


12/81 


$ 


1 . 



780.67!$ 


32.441$ 


144.031$ 


330.92 1$ 


101.17 


669.08!$ 


31.14!$ 


144.031$ 


443,81 1$ 


132.31 


556.19!$ 


29.821$ 


144.03!$ 


558.021$ 


162.13 


441.98!$ 


28.49!$ 


144.031$ 


673.561$ 


190.62 


326.44!$ 


27.14!$ 


144.03!$ 


790.45!$ 


217.76 


209.55!$ 


25.781$ 


144.03!$ 


908.70!$ 


243.54 


091.301$ 


24.40!$ 


144.031$ 


1 .028.331$ 


267.94 


971.67!$ 


23.00!$ 


144.031$ 


1 ,149.361$ 


290,94 


850.64!$ 


21.59!$ 


144.03!$ 


1 ,271 .80!$ 


312.53 


728.20!$ 


20.161$ 


144.031$ 


1 ,395.67!$ 


332.69 


604.33!$ 


18.72!$ 


144.031$ 


1 ,520.98!$ 


351.41 


479.02!$ 


17.261$ 


144.031$ 


1 ,647.751$ 


368.67 



Interest Paid DurinS ' 8 1 - l 8 1 is 



$299.94 



01/82!$ 


1 ,352.251$ 


15.781$ 


144.03!$ 


1 ,776.001$ 


384.45 


02/82!$ 


1 ,224.001$ 


14.281$ 


144.031$ 


1 ,905.75!$ 


398.73 


03/82!$ 


1 ,094.25!$ 


12.77!$ 


144.031$ 


2 ,037.01 !$ 


411.50 


04/821$ 


962.99!$ 


11.23!$ 


144.03!$ 


2.169.81 !$ 


422.73 


05/82!$ 


830.191$ 


9.69!$ 


144.03!$ 


2,304.151$ 


432.42 


06/82!$ 


695.851$ 


8.121$ 


144.03!$ 


2,440.061$ 


440.54 


07/821$ 


559.94!$ 


6.531$ 


144.03!$ 


2,577.561$ 


447.07 


08/821$ 


422.44 1$ 


4.931$ 


144.03 1$ 


2,716.661$ 


452.00 


09/82!$ 


283.34!$ 


3.31 !$ 


144.031$ 


2,857.381$ 


455.31 


10/82!$ 


142.62!$ 


1,66!$ 


144.03!$ 


2,999,75!$ 


456.97 


11/82!$ 


0.251$ 


0.00!$ 


0.25!$ 


3,000.00!$ 


456.97 



Interest Paid During x 82- 1 82 is 



$88.30 



Listing 16-8. Third Interaction with LOAN2 
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Output File Name 
Principal 
Interest 
Payment 
11 nf 1 at i on 
Starting Month 
St art in * Year 
Fiscal Month 



10 



Display Level 
Yr Results 
Yr Interest 
All Ualues 



i 


L A 


N 


3 A Y M E 


NT S U f 


MARY 


1 


: 


Interest 


Rate 


14.00X 


Inflation 


Rate 10.00Z 


1 


IDate ! P 


rinc i pa 1 IP! 


us Interest! Payment IPrincipal Pai d ! In t e res t Paid! 


: 11/801$ 


3,000.001$ 




35.00!$ 


144.031$ 


109.031$ 


35.001 


: i2/8o:$ 


2.864.95!$ 




33.42!$ 


142.731$ 


217.35!$ 


68.11! 


:oi/8i :$ 


2.733.391$ 




31 .881$ 


141.581$ 


325.29!$ 


99.45! 


102/81 :$ 


2,602.35!$ 




30.36!$ 


140.42!$ 


432.71 !$ 


129.00! 


103/811* 


2,471.83!$ 




28.83!$ 


139.27!$ 


539.601$ 


156.771 


104/81 i * 


2,341 .851$ 




27.321$ 


138.121$ 


645.941$ 


182.80! 


105/81 :* 


2,212.44!$ 




25. Bl 1$ 


136.97!$ 


751 .711$ 


207.08! 


106/81 :* 


2,083.60!$ 




24.31 1$ 


135.821$ 


856.90!$ 


229.65! 


107/81 1$ 


1 ,955.36!$ 




22.81 !$ 


134.661$ 


961 .48!$ 


250.52! 


108/81 i$ 


1 ,829.701$ 




21.34!$ 


133.651$ 


1 ,066.60!$ 


269.99! 


109/81 !$ 


1 ,702.581$ 




19.86!$ 


132.50!$ 


1 ,170.05!$ 


287.521 


! 10/81 !$ 


1 ,576.11!$ 




18.381$ 


131.35!$ 


1 ,272.85!$ 


303.41 1 


1 


Interest 


Paid 


Durin9 l B0- '81 is 


$332.69 


1 


: n/81 :$ 


1 .451.91 


$ 




16.941$ 


130.34!$ 


1 .376.48!$ 


318.02! 


! 12/81 i$ 


1 .326.68 


$ 




15.481$ 


129.191$ 


1 ,478.031$ 


330.691 


101/821$ 


1 .203.50 


$ 




14.04!$ 


128.181$ 


1 ,580.641$ 


342.16! 


102/82!$ 


1 ,079.56 


$ 




12.59!$ 


127.03!$ 


1 ,680.871$ 


351.67! 


103/821$ 


957.46 


$ 




11.17!$ 


126.02!$ 


1 ,782.38!$ 


360.06! 


104/821$ 


835.87 


$ 




9.741$ 


125.01 !$ 


1 ,883.39!$ 


366.92! 


105/821$ 


714.79 


$ 




8.341$ 


124.00!$ 


1 ,983.87!$ 


372.31! 


106/82!$ 


594.25 


$ 




6.93!$ 


123.001$ 


2,083.81 !$ 


376.22! 


!07/82l$ 


474.26 


$ 




5.53!$ 


121.991$ 


2 ,183. 181$ 


378.66! 


108/82!$ 


354.84 


$ 




4.14!$ 


120.98!$ 


2 ,281 .991$ 


379.68! 


!09/82!$ 


236.02 


$ 




2.75 1$ 


119.97!$ 


2,380.19!$ 


379.27! 


! 10/82!$ 


117.80 


$ 




1.37!$ 


118.961$ 


2,477.79!$ 


377.451 


! 


Interest 


Paid 


During 1 81- 1 82 is 


$124.28 


1 


! 11/82!$ 


0.20!$ 




0.00!$ 


0.20!$ 


2,457.001$ 


374.25! 


! 


Interest 


Paid 


Durins v 81 - v 82 is 


$0.00 


1 
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16.4 Computation of Depreciation Schedules 

The final example of commercial processing involves evaluating depreciation sched- 
ules. Listing 16-10 shows the program called DEPREC that reads several input values 
and prints a table of output according to one of three different depreciation schedules: 

■ straight-line 

■ sum of the years 

■ double declining 

The program also accounts for bonus depreciation during the first year, reduction 
in taxable income due to sales tax, and investment tax credit on new or used equipment. 

Listings 16-11 through 16-15 illustrate sample interaction with DEPREC using var- 
ious input parameters. 

16.4.1 General Algorithms 

DEPREC uses the following general algorithms: 

■ Investment Tax Credit (ITC) is assumed to be 10% of the selling price applied to 
the full price of new equipment, or up to $100, 000 in the case of used equipment. 
(See the %REPLACE statement, line 11.) 

■ Bonus depreciation is assumed to be 10% of the selling price, up to a maximum 
of $2,000. (See lines 12 and 13.) 

■ Under all three depreciation schedules, the amount to depreciate is taken as the 
difference between the selling price, minus the bonus depreciation, and the 
residual value of the equipment. 

■ Under all three schedules, the depreciation value computed for the first year is 
prorated by month through the remainder of the fiscal year, not including bonus 
depreciation. 
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■ In straight-line depreciation, the amount to depreciate is spread uniformly over 
the number of years in which the depreciation occurs. 

■ For the sum of the years, the year values are summed starting at 1, through the 
number of years in which depreciation takes place: 

ys = 1+2 + 3 + ...+ years 

■ The depreciation is distributed over the total number of years by computing 
years/ys multiplied by the depreciation value for the first year, (years-l)/ys 
multiplied by the remainder for the second year, and so forth, until the last 
year, in which 1/ys multiplied by the remaining depreciation value is taken. 

■ For double declining, yearly depreciation is computed as the book value divided 
by the number of years, which is then multiplied by 2 for new equipment, or 
1.5 if the equipment is used. 

DEPREC first reads the selling price, residual value, percentage sales tax, the per- 
centage income tax bracket, the number of months remaining in the current fiscal year, 
and the number of years in which to depreciate the equipment. It then asks whether 
the equipment is new or used, and reads the depreciation schedule code for the sub- 
sequent report. 

1 a /a******************************************************/ 

2 a /* This program calculates three kinds of depreciation */ 

3 a /* schedules: st rai sht_l ine i suiii_of _the_y ea rs t and */ 
fl a /* double_declinin^. #/ 

5 a /***#***##*********************##*****#***##**###***##*#/ 

6 a depreciate: 

7 b procedure options(main)i 
8b 'I replace 

9 b clear_screen by w ' z ' t 

10b indent b y 1 5 » 

11 b ITC_rate by .1 , 

12b bonus_ rateby.lt 

13 b bonus max by 20005 



in b 
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15b declare 

16 b sel 1 insl_price decimal(8»2)» 

17 b ad Just ed_p rice dec imal ( 8 >2) i 

18 b residual_value dec imal (8 >2) > 

19 b year_value decimal(8>2)» 

20 b depreciation_value dec imal ( 8 »2) > 

21 b total_depreciat ion dec imal ( 8 »2 ) > 

22 b bocK_value dec imal (8 >2 ) i 

23 b tax_rate decimal ( 3 »2 ) » 

24 b sales_tax decimal ( 8 >2) i 

25 b tax_bracKet decimal(2)» 
2G b FYD decimal(B»2) , 

27 b ITC decimal(8,2) > 

28 b bonus_dep decimal ( 8 ,2) t 

29 b mont hs_remain in 1 decimal(2)t 

30 b new cha ract e r ( 4 ) > 

31 b factor decimal (2 >1 ) » 

32 b years decimal(2)> 

33 b year_sum decimal(3)» 

34 b current_year decimal(2)» 

35 b select_sched characte r ( 1 ) 5 

36 b 

37 b declare 

38 b copy_to_list characterful)* 

39 b output file variable* 

40 b ( sy sprint > list) file! 

41 b 

42 b declare 

43 b schedules character(3) static initial ( l syd')> 

44 b schedule (0:3) entry variable! 

45 b 

48 b schedule (0) = error! 

47 b schedule (1) = s t rai 3ht_l ine ! 

48 b schedule (2) = sum_of_y ea rs ! 

49 b schedule (3) = doub 1 e_dec 1 in in i ! 

50 b 

51 b open file (sysprint) stream print paSesize(O) 

52 b t i 1 1 e ( '$con ' ) ! 

53 b ■ 
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54 


c 


55 


c 


5B 


c 


57 


c 


58 


c 


59 


c 


GO 


c 


61 


c 


G2 


c 


G3 


c 


G4 


c 


65 


c 


66 


c 


67 


c 


G8 


c 


69 


c 


70 


c 


71 


c 


72 


c 


73 


c 


74 


c 


75 


c 


76 


c 


77 


c 


78 


c 


79 


c 


80 


c 


81 


c 


82 


c 


83 


c 


84 


c 


85 


c 


86 


c 


87 


c 


88 


c 


89 


c 


90 


c 


91 


c 


92 


c 


93 


c 


94 


c 


95 


c 


96 


c 


97 


b 



do w h i 1 e ( 
put 1 i 
pat sk 
Set li 
put 
Set 
put 
Set 
put 
Set 
put 
Set 
put 
Set 
put 
Set 
put e d 



Set li 
put 1 i 
Set 1 i 
if cop 

ope 
factor 
if new 

f ac 
sal es_ 
if new 

ITC 
>— e 1 se 

ITC 
b o n u s_ 
if bon 

bon 
put 1 i 
call d 
if cop 

cal 
put sk 
Set sk 
end i 



M 'b 
st ( c 
ip(3 
st( s 
st( v 
st ( r 
st( v 
st ( t 
st( v 
st ( t 
st( l 

St ( (tl 

st( * 

St ( V 

st( * 
st (n 
it( % 



st ( s 
st( * 
st ( c 
y_t o 
n fi 
= 1 

tor 
tax 



) ; 
lea 
) 1 
ell 
" i '" 
es i 
'" i " 



ew ) 



el e 
" i " 
opy 
_li 
let 
,5! 
yes 
= 2 
= d 
yes 
ell 



r_s 

ist 

ins 

iRe 

dua 

iSa 

rat 

iTa 

b ra 

iPr 

hs_ 

iHo 

s) ; 

iNe 

i 

iSc 

iSt 

iSu 

iDo 

ct_ 

iLi 

_to 

st 

lis 



c re 
( * - 
_p r 
sid 

1 M 

les 
e) ; 
x B 
eke 
oRa 
rem 
w M 



e n i * " i '" i " i D e p r e c i a t i o n Schedule') ! 
i'iSellinS Price? ')! 
ice ) ! 



ual Value? 
al ue ) H 
Tax U,)? 

racket(7,)? 
t) 5 

te Months? 
ain ins ) 5 
any Years? 



w? (yes/no ) 



h e d u 1 e : ' t 

rai Sht (s ) ' t 

m - o f - Y r s ( y ) ' t 

uble Dec (d)? ') ( a t s K i p ) i 

s c h e d ) i 

st? (yes/no) ' ) i 

_list ) ; 

= l ves ' then 

t) stream print title( v $lst')) 



'then 

,o; 

ecimal ( s e 1 1 inS_p ri ce*t ax_rat e tl2»2)/100+.005i 
' ! sell ins_price <= 100000.00 then 
ins price * ITC rate i 



= 100000 * ITC_ratei 
dep = se 1 1 in S_p r ice * bonus_rate? 
us_dep > bonus_Max then 
u s_d e p = b o n u s_m a x i 
st (c 1 ea r_5c re en ) i 
isplay(sysprint) i 
y_t o_l ist = 'yes 
1 display(list)! 
ip list( w 'i'i' s i 
ip(2) ; 



then 

Type RETURN to Continue')! 



Listing 16-10. (continued) 



225 



PL/I Programming Guide 



16.4 Computation of Depreciation Schedules 



98 


b 


99 


b 


100 


b 


101 


b 


102 


b 


103 


b 


104 


c 


105 


c 


106 


c 


107 


c 


108 


c 


109 


c 


110 


b 


111 


b 


112 


b 


113 


b 


114 


b 


115 


c 


116 


c 


117 


c 


118 


c 


119 


c 


120 


b 


121 


b 


122 


b 


123 


b 


124 


b 


125 


c 


126 


c 


127 


c 


128 


c 


129 


c 


130 


c 


131 


c 


132 


c 



/*#*#*******#*******#*#*#***#*#*#********#♦***#*###****/ 
/* This procedure displays the various depreciation */ 
/* schedules. It calls the app ropri ate schedule with */ 
/* an index into an array of entry constants. */ 
/♦♦♦♦ft**********************************************-***/ 
display : 

procedure(f) 5 

declare 
f file! 

output = f i 

call schedule (index ( schedules tsel ect_sched )) i 
end display 5 



/* This is a Global error recovery routine. */ 

error: 

procedure? 

put file (output) e d i t ( M n valid Schedule - 
(paSe tcoluii)n(indent) »x (8) >a) 5 

call 1 ine ( ) ! 
end error? 



Enter s> y » or d') 



/***#****##*##*#***##*****#***#***#♦##***#***********###/ 
/* This procedure computes st rai 3ht_l ine depreciation. */ 

straisht_line: 
procedure i 

ad Justed_price = se 1 1 in 3_p ri ce - bonus_dep? 
put file (output) edit< v S TRAIGHT LINE') 

(pafle»coluffln( indent) »x ( 14) >a) ? 
call h e a d e r ( ) 5 

depreciation_val ue = ad Just ed_price - res idual_value 5 
booK_value = ad Just ed_p ri ce i 
total depreciation = 05 
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133 
134 
135 
136 
137 
138 
139 
1 40 
141 
142 
143 
144 
145 
14G 
147 
148 
149 
150 
151 
15Z 
153 
154 
155 
15B 
157 
158 
159 
160 
161 
162 
163 
164 



t— do c 



i — e 
d 
t 
b 



end i 
call 
end s t ra 



urren 
e a r_v 
f cur 
o ; 
year 
FYD 
nd i 
ep rec 
o t al_ 

o o K u 

all p 



t_y ea r = 1 to years! 

alue = decimal ( dep rec iat i on_val ue/yea rs »8 »2) + .005! 

rent_y ea r = 1 then 

_ualue = year_Malue * months_re(Tiain in i I 12! 
= yea r_ value! 

iation_ualue = de p rec i at i on_ual ue - year_ualuei 
depreciation = to tal_dep rec i at i on + year_ualue! 
alue = ad Jus t ed_p ri ce - t otal_dep rec i at ion 5 
rint 1 ine ( ) 5 



sumnia ry ( ) ! 
i tf h t line! 



/* This procedure computes depreciation based on */ 
/* the suM_of _the_y ea rs . */ 

sum_of_y ea rs : 
procedure 5 

ad jus ted_p ri ce = se 1 1 inS_p ri c e - bonus_dep! 
put file (output) edit( x S UM OF THE YEARS') 

(pa3etcolumn(indent) »x ( 1 1 ) »a) ! 
call header()i 

dep rec i at i on_ual ue = ad Jus ted_p ri ce - res i dual_ual ue ! 
booK_value = ad justed_pri ce i 
total_depreciat ion = 0! 
year_suM = 5 
r — do current_year = 1 to years! 

year_sum = year_suM + cu r rent_year ! 
end 5 
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165 c 
1S6 d 
1G7 d 

168 d 

169 d 

170 e 

171 e 

172 e 

173 e 
17^ d 

175 d 

176 d 

177 d 

178 d 

179 c 

180 c 

181 b 

182 b 

183 b 

184 b 

185 b 

186 b 
18 7 c 

188 c 

189 c 

190 c 

191 c 

192 c 

193 c 

194 c 

195 d 

196 d 

197 d 

198 d 

199 e 

200 e 

201 e 

202 e 
203 



do current_yea r = 1 to years? 

year_ualue = decimal ( deprec i at ion_value * 

(years - current_year + 1)»12»2)/ year_sum + ,0055 

if current_year = 1 then 

i— do ; 

year_ualue = year_Malue * month5_re(nainin3 / 125 
FYD = yea r_ual ue 5 
end 5 
depreciat ion_yalue = depreciat ion_ualue - year_ualue 5 
total_depreciat ion = t otal_dep reci at ion + year_value5 
book_value = ad just ed_p rice - total_dep rec iat ion 5 
call p rint__line ( ) i 
end 5 

call summary ( ) ! 
end sum of years! 



205 
206 
207 
208 
203 
210 

212 



/* This p r 

/* depreci 

/*#****#** 

double_dec 

proced 

adjust 

put f i 



call h 

deprec 

booK_y 

total_ 

do cur 

wh i 

yea 

if 



if 

dep 
tot 
boo 
cal 

end ! 

call s 
end double 



a********-**************************/ 
ocedure computes double_declinins */ 
at i on . */ 

1 i n i n 3 : 

ure i 

ed_price = sel 1 in sf_p ri ce - bonus_dep! 

le (output) edit^D OUBLE DECLINING') 

( pa3e icolumn(indent) »x ( 10) »a) ! 
eade r( ) ! 

iation_ualue = ad jus ted_p rice - residual_value 5 
alue = ad Justed_price 5 
depreciation = 5 
rent_year = 1 to years 
le ( depreci at ion_value > 0)5 

r_value = dec imal ( book_v alue/years »8 »2) * factor+.O05i 
current_year = 1 then 
do i 

year_ualue = year_value * months_remain in* / 12! 

FYD = yea r_val ue ! 
end ! 

year_ualue > depreciat ion_v alue then 
year_ value = dep rec i at i on_ual ue ! 

reciat ion_i.ialue = depreciation_value - year_valuei 
al deprec iat ion = total_deprec iat ion + year_value! 
K_ualue = ad justed_price - total_depreciation ! 
1 p rint_l ine ( ) ! 

ultima ry ( ) ! 
declining; 
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Z13 


b 


214 


b 


215 


b 


216 


b 


217 


c 


218 


c 


213 


c 


220 


c 


221 


c 


222 


c 


223 


c 


224 


c 


225 


c 


22G 


c 


227 


c 


228 


c 


229 


c 


230 


c 


231 


c 


232 


c 


233 


c 


234 


c 


235 


c 


236 


c 


237 


c 


238 


c 


239 


c 


240 


c 


241 


c 


242 


b 


243 


b 


244 


b 


245 


b 


246 


b 


247 


c 


248 


c 


249 


c 


250 


c 


251 


c 


252 


c 


253 


c 


254 


c 


255 


b 



/* This procedure prints an output header record. * / 
/a*************************************************/ 
header: 

procedure 5 

declare 

new or used character(5)! 



if new = v y es ' then 

new_or_used = ' New'! 
else 

new_or_used = ' Used'! 
put file ( output ) edi t ( 

v ! ' ise 1 1 in $_p rice + sal es_t ax >new_or_used » 

residual_ualue > ' Residual Value!'* 
x ! ' »months_reiTiainin 1 1 ' Months Left '» 

tax_rate » "I Tax ' >tax_b racket t * X Tax Bracket 
(2( skip icolumnt indent) * a ) t 
2(p 1 B$$»$$$,*$9.V99' ta) » 
skip tcolumn( indent) ,a »x(5) >f (2) »a >2( x(2) tp'B99' ta)) i 



' ) 



put file ( output ) edi t ( 



Depreciation 
For Year 



Depreciation 
Remaining 



Book Value 



(skip tcolumn (indent) >a)! 
end header? 

/******#*##*****#*********#*#♦*#*#*#***#*#*#/ 
/* This procedure prints the current line. */ 

p rint_l ine : 

procedure ! 

put file (output) edit( 
' ! ' icur ren t_y ea r » 
' ! ' >v ea r_ual ue » 
' ! ' >dep rec i at i on_ual ue > 
' ! ' »book_y al ue i ' ! ' ) 

(skip»column(indent) »a»f(2) >4(a»p'$z»; 
-end print 1 ine 5 



:z »zz9u.99' ) ) 5 
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256 


b 


257 


b 


258 


b 


259 


b 


260 


b 


261 


c 


262 


c 


263 


c 


2G4 


c 


265 


c 


266 


c 


267 


c 


268 


c 


269 


c 


270 


c 


271 


c 


272 


c 


273 


c 


274 


c 


275 


c 


276 


c 


277 


c 


278 


c 


279 


c 


280 


c 


281 


c 


282 


c 


283 


c 


28-3 


c 


285 


b 


286 


b 


287 


b 


288 


b 


289 


b 


290 


c 


291 


c 


292 


c 


293 


c 


29a 


c 


295 


b 


296 


b 


297 


b 



/**#*#***##*##****#*#******#*##*#***#********##*♦♦*#/ 
/* This procedure prints the summary of values for */ 
/* each type of depreciation schedule. */ 

-summa ry : 

procedure! 
declare 

adJ_ITC decimal (8»2) » 
total dec imal ( 8 »2 ) » 
direct decimal (8 >2) ! 

call 1 ine ( ) 5 

adJ_ITC = ITC * 100 / tax_b racket! 

total = FYD + sales_tax + adJ_ITC + bonus_depi 

direct = total * tax_bracket / 100! 

put file ( output ) ed i t ( 

First Year Reduction in Taxable Income 



Depreciation 
Sales Tax 
ITC (Adjusted) 
Bonus Depreciation 



.FYDf 

»sal es_tax » 
tad J_ITC , 
tbonus_dep i 



• end 



Total for First Year ' (total* 
Direct Reduction in Tax ' »direct* 

(2(sKiPtcolumn(indent) *a) (2(4(sKip»column(indent) 

p'$z»zzz»zz9u.99' *x (3) »a ) *skip»column(indent) *a ) ) 

call 1 ine ( ) 5 

summary ? 



/ * This procedure prints a line of dashes. */ 

line: 

procedure i 

put file (output) edit( 

(sKiPtcolumn(indent) » a ) ! 
■ end 1 ine I 



end depreciates 
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16.4.2 Selecting the Schedule 

There are two constructs in DEPREC that merit special consideration. 

DEPREC uses an array of ENTRY variables to select one of three schedules. Line 
42 defines the array with a subscript range of zero to three. Lines 46 to 49 initialize 
the individual elements of the array, and allow indirect calls to either the ERROR 
subroutine or one of the depreciation schedule handling subroutines. The actual calls 
to the subroutines occur later in the program. 

The schedule selection takes place on line 74, where DEPREC reads one of the 
characters s, y, or d from the console into the character variable select_sched. Line 93 
then invokes the DISPLAY subroutine which performs the actual dispatch to the sched- 
ule handler with the statement on line 108: 

call schedule (index (schedules>select_sched)) ! 

This particular statement works as follows. Line 43 defines the variable schedules, 
and initializes them to the character string 'syd', where each letter corresponds to one 
of the schedule-handling following subroutines: 

syd 
123 

double_declining 

sum_of_years 

straight_line 



Therefore, the statement 
call schedule (iridex(schedulestselec t_s c h e d ) ) 5 

is equivalent to, 

call schedule ( inde x ( sv d >se 1 ect_s ched ) ) 5 

and for the valid inputs s, y, or d, produces 1, 2, or 3 respectively. 
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Thus, if select_sched is s, the call statement evaluates to, 

call schedule(l); 

which calls the subroutine STRAIGHT_LINE. Similarly, an input of y or d evaluates 
to, 

call schedule(2)i or call schedule(3)» 

producing a call to SUM_OF_ YEARS or DOUBLE_DECLINING respectively. 

If the value of selectsched is not s, y, or d, then the INDEX function returns a zero 
value. All invalid character input values produce, 

call schedule(O)? 

which calls the ERROR subroutine and prints the error message. 

16.4.3 Displaying the Output 

Another construct of DEPREC is the output file variable, defined on line 39. During 
the parameter input phase, DEPREC prompts you with: 

List? (yes/no) 

A yes response sends the output from the program to both the console and the list 
device. 

Line 40 declares two file constants, sysprint and list, to address the console and the 
list device. DEPREC first opens the console file, line 51, using an infinite page length 
to avoid form-feed characters. 
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On any iteration of the main DO-group, if you give an affirmative response on line 
77, DEPREC subsequently opens the list device, line 78. This statement can be executed 
several times during a particular execution of the program, but only the first OPEN 
statement has any effect; PL/I ignores the OPEN statement if the file is already open. 

Line 91 calls the DISPLAY subroutine to compute and display the output report for 
a specific set of input values. DISPLAY has a single actual parameter consisting of the 
file constant sysprint that is defined as the formal parameter f on line 104. Line 107 
assigns the formal parameter to the global variable output. Subsequent PUT statements 
write data to the console, producing the first report. 

On line 92, if the variable copy_to_list has the character value yes, then DEPREC 
calls DISPLAY once again. This time, the actual parameter is list, corresponding to the 
system list device. Thus, the output file variable is indirectly assigned the value list, 
and all PUT statements that reference file output send data to the printer. This results 
in both a soft and hard copy of the report. 

DEPREC uses several different forms of decimal arithmetic. Examine the various 
declarations while cross-checking the output formats with the displayed results. 
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Pi>dep rec 



Depreciation Schedule 



Selling Price? 


ZOOOOO 


Residual Value? 


40000 


Sales Tax (Z)? 


6 


Tax Bracket(Z)? 


50 


ProRate Months? 


10 


How Many Years? 


7 


New? (yes/no) 


no 


Schedule: 




Straight (s) 




Sum-of-Yrs (y) 




Double Dec (d)? 


d 


List? (yes/no ) 


no 




DOUBLE 



DECLINING 



$212*000.00 Used 
10 Months Left 



$40*000.00 Residual Value 
06% Tax 50% Tax Bracket 



Y ! Depreciation 
r ! For Year 



Depreciation 
Remain ins 



Book Value 



$ 


35 


.357 


14 


$ 


122 


.642 


86 


$ 


162 


.642 


86 


$ 


34 


.852 


04 


$ 


87 


.790 


82 


$ 


127 


.790 


82 


$ 


27 


.383 


75 


$ 


60 


.407 


07 


$ 


100 


.407 


07 


$ 


21 


.515 


79 


$ 


3B 


.891 


28 


$ 


78 


.891 


28 


$ 


16 


.905 


27 


$ 


21 


.986 


01 


$ 


61 


.986 


01 


* 


13 


.282 


71 


$ 


8 


.703 


30 


$ 


48 


.703 


30 


$ 


8 


.703 


30 


$ 







00 


$ 


40 


.000 


00 



First Year Reduction in Taxable Income 



Depreciation 
Sales Tax 
ITC (Adjusted) 
Bonus Depreciation 

Total for First Year 
Direct Reduction in Tax 



$ 35.357,14 

$ 12.000.00 

$ 20.000.00 

$ 2.000,00 

$ 69.357,14 

$ 34.678,57 



Listing 16-11. First Interaction with DEPREC 
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Depreciation Schedule 



Selling Price? 
Residual Value? 
Sales Tax (1)7 
Tax Bracketm? 
ProRate Months? 
How Many Years? 
New? (yes/no) 
Schedule : 
Straight (s) 
Sum-of-Yrs (y) 
Double Dec (d)? 
List? (yes/no) 



SUM OF 



THE YEARS 



! $2 


L2 


»000.00 New 




$40 ,000,00 


Residual Value! 


1 




8 


Months Left 


06% Tax 501 


Tax 


B r a c K e t ! 


! Y 


Depreciation 




depreciation 




BooK 


Value ! 


I r 






: or Year 




Remain in 3 






! 


! 1 


$ 




26,333.33 


$ 


131 ,666.67 


$ 


171 


,666.67 ! 


i rt 


$ 




28,214,28 


$ 


103,452.38 


$ 


143 


,452.38 ! 


! 3 


$ 




18,473.64 


$ 


84,878.74 


$ 


124 


,978.74 ! 


! 4 


$ 




12,139.82 


$ 


72,838.82 


$ 


112 


,838,92 ! 


! 5 


$ 




7,804.17 


$ 


65,034.75 


$ 


105 


,034,75 ! 


! 6 


$ 




4,645.34 


$ 


60,389.41 


$ 


100 


,389.41 ! 


1 7 


$ 




2,156.76 


$ 


58,232.65 


$ 


98 


232.65 ! 


! 




F 


i rst Year Re 


>d 


iction in Tax< 


lbl 


e Income ! 



Depreciation 
Sales Tax 
ITC (Adjusted) 
Bonus Depreciation 

Total for First Year 
Direct Reduction in Tax 



$ 26,333,33 

$ 12,000.00 

$ 40,000.00 

$ 2,000.00 

$ 80,333.33 

$ 40,166.66 



Listing 16-12. Second Interaction with DEPREC 



^RMATION PRE 



t % 1 ^ R ^ ) P p. I jF.f •! 
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Depreciation Schedule 



Selling Price? 


310000 


Residual Value? 


30000 


Sales Tax (I)? 


t 


Tax Bracketm? 


i 


ProRate Months? 


12 


How Many Years? 


5 


New? (yes/no ) 


yes 


Schedule : 




Straight (s) 




Sum-of-Yrs (y) 




Double Dec (d)? 


d 


List? (yes/no) 


no 



DOUBLE 



DECLINING 



5328,600.00 New 
12 Months Left 



$30,000.00 Residual Value 
OB'X Tax 501 Tax Bracket 



! Y 


Depreciation 


Depreciation 


B o o K Value ! 


! r 




For Year 


Remain in i 


1 


! 1 


$ 


123,200.00 


$ 154,800,00 


$ 184,800.00 ! 


; 2 


* 


73,920.00 


$ 80,880.00 


$ 110,880.00 ! 


! 3 


$ 


44,352.00 


$ 36,528.00 


$ 66,528.00 ! 


! 4 


$ 


26*611.20 


$ 9,916.80 


$ 39,918.80 ! 


! 5 


$ 


9,916.80 


$ 0.00 


$ 30,000.00 i 


! 




First Year Rf 


eduction in Tax 


ib le Income ! 






Depreciation 


$ 


123,200,00 ! 






Sales Tax 


$ 


18,600,00 ! 






ITC (AdJuste 


i) $ 


62,000.00 : 






Bonus Deprec 
Total for Fi 


i at i on $ 


2,000.00 ! 


rst Year $ 


205,800,00 ! 






Direct Reduc 


tion in Tax $ 


102,900,00 ! 



Listing 16-13. Third Interaction with DEPREC 
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Depreciation Schedule 



Bellini Price? 
Residual Value? 
Sales Tax (I)? 
Tax Bracketm? 
ProRate Months? 
How Many Years? 
New? (yes/no ) 
Schedule : 
Straight (s) 
Sum-of-Yrs (y) 
Double Dec (d)? 
List? (yes/no) 



STRAIGHT LINE 



$328,600,00 New 
12 Months Left 



$30*000,00 Residual Ualue 
0B1 Tax 507, Tax Bracket 



Depreciation 
For Year 



Depreciation 
Remaining 



Book Ualue 



$ 55*600.00 

$ a4.a80.oo 

* 35.584.00 

$ 28.467.20 

$ 22.773.78 



!$ 222.400.00 

!$ 177.820.00 

!$ 142.338.00 

!$ 113.8BB.B0 

!$ 81.095.04 



$ 252.400.00 

$ 207.820.00 

$ 172.336.00 

$ 143.868.80 

$ 121.095.04 



First Year Reduction in Taxable I n c owe 



Depreciation 
Sales Tax 
ITC (Adjusted) 
Bonus Depreciation 

Total for First Year 
Direct Reduction in Tax 



$ 


55 


.800 


00 


$ 


18 


.800 


00 


$ 


82 


.000 


00 


$ 


2 


.000 


00 


$ 


138 


.200 


00 


* 


89 


.100 


00 



Listing 16-14. Fourth Interaction with DEPREC 

End of Section 1 6 



References: Sections 3.1, 3.5, 4.2, 11.3 LRM 
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Section 17 
Internal Data Representation 



This section describes how PL/I represents data internally. This knowledge is vital 
when using based variables to overlay storage so you do not destroy adjacent storage 
locations. Knowledge of the internal data representation is also useful when so you 
want to interface assembly language routines with high-level language programs and 
the PL/I Run-time Subroutine Library. 

Note: the discussion in this section applies to the implementation of PL/I for both 8- 
bit and 16-bit processors. 



17.1 FIXED BINARY Representation 

PL/I stores FIXED BINARY data in one of two forms, depending upon the declared 
precision. It stores FIXED BINARY values with precision 1-7 in single-byte locations, 
and values with precision 8-15 in a word (double-byte) location. With multibyte storage, 
PL/I stores the least significant byte first. 

PL/I represents all FIXED BINARY data in two's complement form, allowing single- 
byte values in the range -128 to + 127, and word values in the range -32768 to + 32767. 

The following figure shows the representation of storage in both single-byte and 
double-byte locations for the values 0, 1, and -1. Each boxed value represents a byte 
of memory, and is shown in both binary and hexadecimal values. 



FIXED BINARY(7) 



FIXED BINARY(15) 



0000 0000 



0000 0000 0000 0000 



00 



00 00 



Figure 17-1. FIXED BINARY Representation 
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FIXED BINARY(7) 



0000 0001 



01 



FIXED BINARY(15) 



0000 000.1 0000 0000 



01 00 



FIXED BINARY(7) 



1111 1110 



FE 



FIXED BINARY(15) 



1111 1110 



1111 1111 



FEFF 



17.2 FLOAT BINARY Representation 

PL/I stores single-precision floating-point binary numbers in four consecutive bytes. 
The 32 bits contain the following fields: a 23 -bit mantissa, a sign bit, and an 8 -bit 
exponent. The least significant byte of the mantissa appears first in memory. 



exponent 


s 


mantissa 



32 



23 22 



Figure 17-2. Single-precision Floating-point Binary 

PL/I normalizes floating-point numbers so the most significant bit of the mantissa is 
always 1 for nonzero numbers. Because the most significant bit of the mantissa must 
be 1 for nonzero numbers, PL/I replaces this bit position with the sign. PL/I represents 
a zero mantissa with an exponent byte of 00. 
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17.2 FLOAT BINARY Representation 



In order to make certain kinds of comparisons easier, the binary exponent byte has 
a bias of 80 (hexadecimal), so that 81 represents an exponent of 1 while 7F represents 
an exponent of -1. 

Suppose a floating-point binary value appears in memory as shown in the following 
example: 



00 


00 


40 


81 



Low High 

In this case, the mantissa is a bit stream of the form 

4 

0100 0000 . . . 

and the high-order bit equal to zero indicates that the mantissa sign is positive. Nor- 
malizing the number produces the bit stream: 

1100 0000 . . . 

The exponent 81 has a bias of 80, so the binary exponent is 1. This means that the 
binary point is one position to the right, resulting in the binary value 

1 100 0000 . . . 

1^1 in binary represents 2°^2" 1 ; therefore 11 base 2 is equivalent to 1.5 base 10. 

00 00 40 81 
is the floating-point binary representation of the decimal number 1.5. 
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PL/I stores double-precision floating-point binary numbers in eight consecutive bytes. 
The 64 bits contain the following fields: a 52-bit mantissa, an 11 -bit exponent with a 
bias of 3FF(hexadecimal), and a sign-bit. 



s 


exponent 


mantissa 



63 62 51 

Figure 17-3. Double-precision Floating-Point Binary 

For example, suppose that a floating-point binary value appears in memory as shown 
in the following: 



00 


00 


00 


00 


00 


CO 


43 


CO 



Low High 

In this case, the mantissa is a bit stream of the form, 

3 C 

0011 1100 0000 . . . 
Normalizing the number produces, 

1001 1110 0000 ... 
The exponent evaluates as follows: 

C 4 

1100 0000 0100 

The high-order bit is 1 so the sign is negative. Ignoring the sign bit yields an exponent 
of, 

4 4 
0100 0000 0100 
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which has a bias of 3FF, so the real exponent is, 

404 
- 3FF 

5 

Therefore, the binary number is, 
1001 11 10 0000 . . . 

which is 39.5 in decimal. Thus, the eight-byte value, 

00 00 00 00 00 CO 43 CO 
is the double-precision float-binary representation of the decimal number -39.5. 

17.3 FIXED DECIMAL Representation 

PL/I stores FIXED DECIMAL data items in packed BCD (Binary Coded Decimal) 
form. Each BCD digit occupies a half-byte, or nibble. PL/I stores the least significant 
BCD pair first, with one BCD digit position reserved for the sign. Positive numbers 
have a sign, while negative numbers have a 9 in the high-order sign digit position. 

The number of bytes occupied by a FIXED DECIMAL number depends upon its 
declared precision. Given a decimal number with precision p, PL/I reserves a number 
of bytes equal to: 

FLOOR((p + 1)11) 

where p varies between 1 and 15. This results in a minimum of 1 byte and a maximum 
of 8 bytes to hold a FIXED DECIMAL data item. 

For example, if you declare the number 12345 with precision 5, then PL/I reserves 
FLOOR((5 + 2)/2) = 3 bytes of storage and represents the number as: 

45 23 01 



243 



17.3 FIXED DECIMAL Representation PL/I Programming Guide 

PL/I stores negative FIXED DECIMAL numbers in ten's complement form. To derive 
the ten's complement of a number, first derive the nine's complement and then add 1 
to the result. For example, the number -2 expressed in ten's complement is, 

(9 - 2) + 1 = 8 
Adding the sign digit gives, 

98 
If you declare -2 with precision 5, then PL/I represents it as: 

98 99 99 

17.4 CHARACTER Representation 

PL/I stores character data in one of two forms, depending upon the declaration. It 
stores fixed-length character strings, declared as CHARACTER(n) in n contiguous 
bytes, with the first character in the string stored lowest in memory. 

PL/I reserves n + 1 bytes for variables declared as CHARACTER(n) VARYING with 
the extra byte holding the character string's length, ranging from to 254. The max- 
imum length of either type of string is 254 characters. 

As an example, suppose the variable A is declared as CHARACTER(20). The assignment 

A = x Walla Walla Wash* 5 

results in the following storage allocation, 

WallabWallabWashxxxx 

where b represents a blank, and x represents an undefined character position. If A is 
declared as CHARACTER(20) VARYING data, PL/I stores the same string as 

10 WallabWallabWashxxxx 

where 10 is the (hexadecimal) string length. 
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17.5 BIT Representation 

PL/I represents bit-string data in two forms, depending upon the declared precision. 
It stores bit strings of length 1-8 in a single byte, and bit strings of length 9-16 in a 
word (double-byte) value. PL/I stores the least significant byte of a word value first in 
memory. Bit values are stored left-justified, and if the precision is not exactly 8 or 16 
bits, the bits to the right are ignored. 

The following figure shows the storage for the bit-string constant values Tb, 'A0'b4, 
and '1234'b4 in both single- and double-byte locations. Each boxed value represents 
a byte. 



BIT(8) 



0000 0001 



BIT(8) 



1010 0000 



0000 0000 0000 0001 


BIT(16) 


0000 0000 1010 0000 


BIT(16) 


0011 0100 0001 0010 



BIT(8) 
N/A 
Figure 17-4. Bit-string Data Representation 



17.6 POINTER, ENTRY and LABEL Data 

PL/I stores variables that provide access to memory addresses as two contiguous 
bytes, with the low-order byte stored first. POINTER, ENTRY, and LABEL data items 
appear as 



LS 


MS 



Figure 17-5. POINTER, ENTRY, and LABEL Data Storage 

where LS denotes the least significant half of the address, and MS denotes the most 
significant portion. MS contains the page address, where each memory page is 256 
bytes, and LS contains the offset within the page. 
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17.7 File Constant Representation 

PL/I associates each file constant with a File Parameter Block (FPB). The FPB occupies 
57 contiguous bytes containing various fields, some of which are implementation 
dependent. 

Note: each file declaration causes a static allocation for the associated FPB. When you 
open the file, there is an additional overhead of 50 bytes, including the operating 
system's FCB and the amount specified for buffer space. The run-time system dynam- 
ically allocates this storage from the free storage area. 



17.8 Aggregate Storage 

PL/I stores aggregate data items contiguously with no filler bytes. Bit data is always 
stored unaligned. Arrays are stored in row-major order, with the rightmost subscript 
varying fastest. 

For example, the declaration 
declare A ( 2 » 2 * 2 ) ? ■ 



results in the following storage allocation: 



111 


1,1,2 


1,2,1 


1,2,2 


2,1,1 


2,1,2 


2,2,1 


2,2,2 



low 



high 



Figure 17-6. Aggregate Storage 

End of Section 1 7 
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This section describes a standard set of conventions for interfacing PL/I programs 
with assembly language routines and with programs written in other high-level lan- 
guages. This section also describes the mechanism for making direct operating system 
calls using a set of optional subroutines not included in the Run-time Subroutine 
Library. 



18.1 Parameter Passing Conventions 

You can pass parameters between a PL/I program and an assembly language routine 
by loading a register pair with the address of a Parameter Block containing pointer 
values. These pointers in turn lead to the actual parameter values. The number of 
parameters and the parameter length and type must be determined implicitly by agree- 
ment between the calling program and called subroutine. The following figure illustrates 
the concept. The address fields are arbitrary. 



Register pair 
HL (8080) 



Parameter Block 



Actual Parameters 




1000: 



BX (8086) 



2000 



3000 



4000 



5000 




2000: 


parameter 1 






3000: 


parameter 2 






'4000: 


parameter 3 




, 


5000: 


parameter n 



Figure 18-1. PL/I Parameter Passing Mechanism 
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The following example illustrates this parameter passing mechanism. Suppose a 
PL/I program uses a considerable number of floating-point divide operations, where 
each division is by a power of two. Suppose also that the iterative loop where the 
divisions occur is speed-critical, and that it is useful to have an assembly language 
subroutine to perform the division. 

The assembly language routine simply decreases the binary exponent of the floating- 
point number for each power of two in the division. Decreasing the exponent effectively 
performs the divide operation without the overhead involved in unpacking the number, 
performing the general division operation, and repacking the result. During the division, 
the assembly language routine can produce underflow, and must signal the UNDER- 
FLOW condition to the PL/I program if this occurs. 

The following three listings show programs that demonstrate parameter passing. 
Listing 18-1 shows the program DTEST, which tests the division operation. Listing 
18-2 shows DIV2.ASM, the 8080 assembly language subroutine that performs the 
division. On line 8, DTEST defines DIV2 as an external entry constant with two 
parameters: a FIXED(7) and a floating-point binary value. Listing 18-3 shows 
DIV2.A86, which is the same subroutine in 8086 assembly language. 

On each iteration of the DO-group, DTEST stores the test value 100 into f (line 13), 
and passes it to the DIV2 subroutine (line 14). At each call to DIV2, DTEST changes 
the value of f to f/(2**i) and prints it using a PUT statement. At the point of call, 
DIV2 receives two addresses that correspond to the two parameters i and f. 

Upon entry, DIV2 loads the value of i to the accumulator, and sets the appropriate 
register pair to point to the exponent field of the input floating-point number. If the 
exponent is zero, DIV2 returns immediately, because the resulting value is zero. 

Otherwise, the subroutine loops at the label dby2 while counting down the exponent 
as the power of two diminishes to zero. If the exponent reaches zero during this counting 
process, DIV2 signals the UNDERFLOW condition. 

In DIV2, the call to Psignal demonstrates the assembly language format for param- 
eters that use the interface. The Psignal subroutine is part of the PL/I Run-time Sub- 
routine Library (PLILIB.IRL). 

This subroutine loads the appropriate register pair with the address of the Signal 
Parameter List, denoted by siglst. The Signal Parameter List, in turn, is a Parameter 
Block of four addresses leading to the signal code sigcode, the signal subcode sigsub, 
the filename indicator sigfil (not used here), and the auxiliary message sigaux that is 
the last parameter. 
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The auxiliary message can provide additional information when an error occurs. 
The signal subroutine prints the message until it either exhausts the string length (32, 
in this case), or it encounters a binary 00 in the string. 

Listing 1 8-4 shows the abbreviated output from this test program. The loop counter 
i becomes negative when it reaches 128, but the DIV2 subroutine treats this value as 
an unsigned magnitude value; thus UNDERFLOW occurs when i reaches — 123. 

1 a /**#****#**##**#***#****#****#**************##*********/ 

2 a /* This program tests an assembly laMuaSe routine to */ 
3a /* do floating-point division. * / 
l\ a /a*****************************************************/ 
5 a ,- — dtes t ; 

procedure options(itiain)i 
declare 

d i u 2 entry(fixed(7)»float)» 

i f ixed(7) t 

f float! 



G b 

7 b 

8 b 

9 b 

10 b 

11 b 

12 c 

13 c 

14 c 

15 c 

16 c 

17 b 

18 b 



-do i = by 1 i 

f = 100 i 

call d i u 2 ( i > f) i 

put skip 1 i s t ( M 00 / 2 **' >i ," = ' <f) i 
-end i 



■ end dtest 5 



Listing 18-1. The DTEST Program 
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title 'division by power of two' 
public d i u2 
extrn ?siSnal 
entry: 

pi - > f i x e d ( 7 ) power of two 

p2 -> floating-point number 
exi t : 

pi -> (unchanged) 

p2 -> p2 / (2**pl) 

div2: !HL = .low(.pl) 

moM e > m i 1 o w ( . p 1 ) 

inx h iHL = .hi<Jh( .pi) 

mov d >m 5DE = . pi 

inx h 5HL = . 1ow(p2) 

ldax d 5a = pi (power of two) 

mov e jfn 5 1 o w ( ♦ p 2 ) 

inx h iHL = ,hish( .p2) 

mov d >m !DE = . p2 

xchs ?HL = .p2 

5 A = power of 2» HL = .low byte of fp num 

inx h 5 to middle of iti an tissa 

inx h 5 to hisfh byte of mantissa 

inx h 5to exponent byte 

in r m 

dcr m ip2 already zero? 

rz ! ret urn if so 
dby2: idivide by two 

ora a icounted power of 2 to zero? 

rz 5 ret u rn if so 

dor a icount power of two down 

dor m icount exponent down 

Jnz dby2 iloop asain if no underflow 

Listing 18-2. DIV2.ASM Assembly Language Program (8080) 
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iunderflow occurred* signal underflow condition 

lxi h is i Si s t i s i Snal parameter list 

call ?si3nal isi^nal underflow 
ret inormallyi no return 

5 

dse 4 

sislst: dw sitfcod iaddress of siSnal code 

dw s i 4 s u b iaddress of subcode 

dw sisfil iaddress of file code 

dw si^aux iaddress of aux message 

i end of parameter vector* start of params 

siScod: db 3 5 03 = underflow 

siSsub: db 128 iarbitrary subcode for id 

sisfil: dw 0000 ino associated file name 

sitfaux: dw undmsS iOOOO if no aux message 

undmss: db 32 < * Unde rf 1 ow in Divide by Two'tO 
end 



Listing 18-2. (continued) 



Routine to divide single precision float value by 2 

cse3 

public d i v2 

ext rn ?s i tfnal : nea r 

entry: 

pi -> fixed(7) power of two 

p2 -> floating point number 
exit: 

pi - > ( unchan Sed ) 

p2 -> p2 / <2**pl) 

div2: iBX = .low< ,p1) 

mov si»Cbx] iSI = . p1 

mov bx »2[bx] iBX = »p2 

lods al iAL = pi (power of 2) 

i AL = power of 2» BX = .low byte of fp num 

cmp byte ptr 3Cbx]»0 ip2 already zero? 
Jz done iexitifso 

Listing 18-3. DIV2.A86 Assembly Language Program (8086) 
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dbvZ: 



o r 


al »al 


Jz 


done 


dec 


al 


dec 


byte pt r 3Cbx] 


jnz 


dbvZ 



i d i u i d e by two 

counted power of 2 to zero? 

return if so 

count power of two down 

count exponent down 

loop aaain if no underflow 



Underflow occurred* signal underflow condition 





MOV 




call 


done : 


ret 




dse i 


sislst 


dw 




dw 




dw 




dw 


5 


end 


si 3cod 


db 


si 3sub 


db 


si*f il 


dw 


si Saux 


dw 


undwss 


db 



bxtoffset si Slst isi.Snal parameter list 
?si^nal isianal underflow 

ino rmal 1 y » no return 



i ad d ress of si 3nal code 

iaddress of subcode 

iaddress of file code 

iaddress of aux message 



offset siScod 
offset sissub 
offset sisfil 
offset si sfaux 
end of parameter vector* start of params 
3 i03 = underflow 

128 iarbitrary subcode for id 

0000 ino associated file name 

offset unditiss" iOOOO if no aux Message 
32 i 'Unde rf low in Divide by Two'»0 



end 



Listing 18-3. (continued) 
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A > d t e s t 












100 / 


2 


*# 





r 


1 


000000E+02 


100 / 


? 


#* 


1 


= 


5 


OOOOOOE+Ol 


100 / 


2 


#* 


>~t 


= 


2 


500000E+01 


100 / 


n 


*# 


3 


= 


1 


250000E+01 


100 / 


? 


** 


a 


= 





G25000E+01 


100 / 


2 


** 


5 


= 


3 


125000E+00 


100 / 


9 


*# 


B 


= 


1 


5G2500E+00 


100 / 


2 


** 


7 


= 





781250E+00 


100 / 


2 


** 


8 


= 


3 


90G250E-01 


100 / 


2 


** 


3 


= 


1 


953125E-01 


100 / 


2 


** 


10 


= 





97B5B2E-01 



100 


/ 


9 


** 


127 


= 





587747E-36 


100 


/ 


2 


*# 


-128 


= 


2 


938735E-37 


100 


/ 


2 


#* 


-127 


= 


1 


4683G7E-37 


100 


/ 


9 


** 


-12G 


= 





734G83E-37 


100 


/ 


2 


** 


-125 


= 


3 


G73419E-3B 


100 


/ 


2 


** 


-124 


= 


1 


83G709E-3B 


100 


/ 


? 


#* 


-123 


= 





918354E-38 


100 


/ 


2 


** 


- 122 


= 


a 


591774E-33 



UNDERFLOW (128). Underflow in Divide By Two 

Traceback: 017F 01 IB 

A> 



Listing 18-4. DTEST Output (abbreviated) 



18.2 Returning Values from Functions 

As an alternative to returning values through a Parameter Block, PL/I has subroutines 
that produce function values that are then returned directly in the registers or on the 
stack. This section shows the conventions for returning data as functional values. 
References to 8086 registers are in parentheses. 
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18.2.1 Returning FIXED BINARY Data 

Functions that return FIXED BINARY data items do so by leaving the result in a 
register, or register pair, depending upon the precision of the data item. 

PL/I returns FIXED BINARY data with precision 1-7 in the A(AL) register, and data 
with precision 8-15 in the HL(BX) register pair. It is always safe to return the value 
in HL(BX), and copy the low-order byte to A(AL) so register A(AL) is equal to register 
L(BL) upon return. 

18.2.2 Returning FLOAT BINARY Data 

PL/I returns single-precision floating-point numbers as four contiguous bytes on the 
stack. The low-order byte of the mantissa is at the top of the stack, followed by the 
middle byte, then the high byte. The fourth byte is the exponent of the number. 

For example, PL/I returns the value 1.5 as: 



00 00 40 81 (low stack) 



SP 

PL/I returns double-precision floating-point numbers as eight contiguous bytes on 
the stack. The low-order byte of the mantissa is at the top of the stack. The exponent 
occupies three nibbles: the eighth byte, and the high-order nibble of the seventh byte. 

For example, PL/I returns the value —39.5 as: 



00 1 00 1 00 1 00 1 00 1 CO 1 43 1 CO | (low stack) 
SP 
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18.2.3 Returning FIXED DECIMAL Data 

PL/I returns FIXED DECIMAL data as 8 contiguous bytes on the stack. The low- 
order BCD pair is at the top of the stack. The number is represented in nine's com- 
plement form, and sign-extended through the high-order digit position, with a positive 
sign denoted by 0, and a negative sign denoted by 9. 

For example, PL/I returns the decimal number —2 as: 

(low stack) — > 



■ 

98 


99 


99 


99 


99 


99 


99 


99 



SP 

18.2.4 Returning CHARACTER Data 

PL/I returns CHARACTER data items on the stack, with the length of the string in 
a register. For example, PL/I returns the string 

x Walla Walla Wash ' 

as shown in the following diagram: 

A (8080) 



10 



W 



h 



W 



irW 



(low stack) 



AL (8086) 



SP 



where register contains the string length 10 (hexadecimal), and the Stack Pointer SP 
addresses the first character in the string. 

18.2.5 Returning BIT Data 

PL/I returns bit-string data in a register, or register pair, depending upon the precision 
of the data item. 

PL/I returns bit strings of length 1-8 in the A(AL) register, and bit strings of length 
9-16 in the HL(BX) register pair. Bit strings are left justified in their fields, so the BIT(l) 
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value true is returned in the HL(BX) register as 80 (hexadecimal). It is safe to return 
a bit value in the HL(BX) register pair and copy the high-order byte in A(AL), so 
register A(AL) is equal to register H(BH) upon return. 

18.2.6 Returning POINTER, ENTRY, and LABEL Variables 

PL/I returns POINTER, ENTRY, and LABEL variables in the HL(BX) register pair. 
When returning a label variable that can be the target of a GOTO operation, the 
subroutine containing the label must restore the stack to the proper level when control 
reaches the label. 

The following program listings illustrate the concept of returning a functional value. 
Listing 18-5 shows the program called FDTEST that is similar to the previous floating- 
point divide test. However, FDTEST includes an entry definition for an assembly 
language subroutine called FDIV2 that returns the result on the stack. Listing 18-6 
shows FDIV2.ASM in 8080 assembly language, and Listing 18-7 shows FDIV2.A86, 
the same routine in 8086 assembly language. 

FDIV2 resembles the previous subroutine DIV2 with some minor changes. First, 
FDIV2 loads the input floating-point value into the BC(CX) and DE(DX) registers so 
that it can manipulate a temporary copy and not affect the original input value FDIV2 
then decreases the exponent field in register B(CH) by the input count, and returns it on 
the stack before executing the PCHL instruction. 

1 a /a***************************************************/ 

2 a /* This program tests the assembly lanSuase routine */ 
3a /* called FDIV2 which returns a FLOAT BINARY value. */ 

4 a /*#*#***##********#****#*#***#************#****■*#*###/ 

5 a f dtest : 

6 b procedure options (main ) 5 
7b declare 

8 b fdiu2 entry (fixed(7) tfloat) returns ( float ) » 

9 b i fixed(7) » 

10 b f float! 

11 b 

12 c do i = by 1 5 

13 c put skip 1 ist ( v 100 / 2 ** ' » i V = ' »f di u2 ( i » 100) ) 5 
14c end? 



15 b 

16 b end f dtest 5 



Listing 18-5. The FDTEST Program 
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f d i u 2 : 



dby; 



title 
publ i < 
ext rn 
entry: 



exit 



stack 



v div by power of two (function)' 
f diu2 

?si3nal 

pi -> f i x e d ( 7 ) power of two 
p2 -> f 1 oat in3-po int number 

pi -> (unchanged ) 
p2 - > (unchanged) 
p2 / (2 ** Pl) 

!HL = .low( .Pl) 

i low ( . pl ) 

!HL = .hish( ,pl) 

;de = .pi 

5HL = ,1ow(p2) 

ia = pl (power of two)' 

!low( . p2) 

5HL = .hiSh(.pZ) 

5DE = ,p2 

iHL = .p2 

power of 2» HL = .low byte of fp num 
E = low mantissa 
to middle of mant i ssa 
D = middle mantissa 
to hi3h byte of mantissa 
C = hi 3h mant issa 
to exponent byte 
B = exponent 
B = 00? 

becomes 00 if so 
to return from float diu 

counted power of 2 to sero? 

return if so 

count power of two down 

count exponent down 

loop a3ain if no underflow 



mou 


e 


tm 


inx 


h 




moo 


d 


tm 


inx 


h 




ldax 


d 




mo v 


e 


tm 


inx 


h 




moy 


d 


tm 


xch3 






A = powe r 


of 


moy 


e 


tm 


inx 


h 




mow 


d 


»m 


inx 


h 




moy 


c 


tm 


inx 


h 




mou 


b 


tm 


in r 


b 




dc r 


b 




jz 


fdret 


! d i v i d e 


b 


y tw 


o ra 


a 




Jz 


f d ret 


dc r 


a 




dc r 


b 




Jnz 


dby2 



5underflow occurredt siSnal underflow condition 
lxi h »si 31 st isi 3nal parameter list 
call ?si3nal 5si3nal underflow 
lxi b»0 icl ear to ze ro 
lxi dtO if or default return 



Listing 18-6. FDIV2.ASM Assembly Language Program (8080) 
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f dret: 


POP 


h 




push 


b 




push 


d 




pchl 




5 


dse 3 




sislst : 


dw 


S i 3 C d 




dw 


s i 3 s u b 




dw 


si3f il 




dw 


s i 3 a u x 


i 


end of 


pa rawe t 


s i 3 c o d : 


db 


3 


s i 3 s u b : 


db 


128 


si sf il: 


dw 





s i 3 a u x : 


dw 


u n d m s 3 


undmstf : 


db 
end 


32) N Un 



? r e c a 1 1 return address 
5 save hi3h order f p num 
5s aye low order fp num 
5 return to callin3 routine 



5 a d dress of si3nal code 
5 address of subcode 
! a d dress of file code 
sad dress of aux m e s s a 3 e 
vector* start of par aw s 
5 03 = underflow 
iarbitrary subcode for id 
5no associated file name 
50000 if no aux wessa3e 
N Underflow in Divide by Two'tO 



Listing 18-6 (continued) 



Division by power of two (function) 



cse 3 

public f d i v 2 

ext rn ?s i 3nal :near 



p 1 - > fixed (7) power of two 
p 2 - > f 1 o a t i n 3 point number 



exit: 



p 1 - > (unchanged) 
p2 - > ( unchan 3ed ) 
stack: p2 / (2 ** pi) 

fdiv2: iBX = ,low( ,pl) 

mov s i t C b x ] 5 S I = . p 1 

lods al iAL = pi (power of 2) 

mov bx »2Ebx] iBX = ,p2 

; AL = power of 2> BX = .low byte of fp num 



MOV 


d x i [ b x ] 


MOV 


ex »2Cbx] 


o r 


ch »ch 


Jz 


f d ret 



5 D X = low and middle mantissa 

5CL = hi3h mantissa) CH = exponent 

5 e x p o n e n t zero? 

5 1 o return from float div 



Listing 18-7. FDIV2.A86 Assembly Language Program (8086) 
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o r 


al *al 


J z 


f d r e t 


dec 


al 


dec 


ch 


Jnz 


d b y 2 
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d b y 2 : i d i u i d e b y two 

i counted power of 2 to zero? 
5 return if so 

i c o u n t power of two down 

icount exponent down 

5 1 o o p a 4 a i n if no underflow 

5 Underflow occurred) signal underflow condition 

mom bx toff set sislstisisnal parameter list 

call ?si£fnal isiSnal underflow 

sub cxtcx iclear result to zero for default return 

mom d x » c x 

fdret: pop bx 5 recall return address 

push ex isaue hish order fp num 

push d x isaue low order fp num 

J m p b x Jreturn to calling routine 
dsesf 

si^lst dw offset s i 3 c o d 5 a d dress of signal code 

dw offset s i 3 s u b Sad dress of subcode 

dw offset sisfil 5 a d dress of file code 

dw offset s i 3 a u x 5 ad dress of aux message 

i end of parameter uecto.rt start of params 

siscod db 3 503 = unde rf low 

s i 3 s u b d b 128 iarbitrary subcode for id 

s i 5 f i 1 d w 0000 ino associated file name 

sisaux dw offset undmssf 50000 if no aux message 

undwss db 32 i v Unde rf low in Divide by Two ' >0 



end 



Listing 18-7. (continued) 



18.3 Direct Operating System Function Calls 

You can have direct access to all the operating system functions through the optional 
subroutines in assembly language programs which are included in source form on your 
PL/I sample program disk. The sample program disk also contains the file REL- 
NOTES.PRN which describes these assembly language programs and several PL/I pro- 
grams that test the various function calls. 

The subroutines in these programs are not included in the standard PLILIB.IRL file 
because specific applications might require changes to the system functions that either 
remove operations to decrease space, or alter the interface to a specific function. If the 
interface to a function changes, you must change the entry point to avoid confusion. 
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Note: be careful when you use these entry points instead of the normal PL/I facilities. 
For example, if you use the MEMPTR function to effect memory management, be 
aware that PL/I uses the dynamic storage area for processing RECURSIVE procedures 
and file I/O buffering. There is no guarantee that the dynamic storage area will not be 
used for other purposes as addtional facilities are added to PL/I. 

Also, when you use the various file maintenance functions, such as DELETE(#19) 
or RENAME (#23), do not access a file that is currently open in the PL/I file system. 
Simple peripheral access, as shown in these examples, is generally safe because no 
buffering takes place. 



End of Section 1 8 
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Section 19 

Dynamic Storage and Stack 

Routines 



This section describes some functions in the PL/I Run-time Subroutine Library (RSL) 
that perform dynamic memory management and manipulate the stack size. 



19.1 Dynamic Storage Subroutines 

The RSL includes a number of functions that provide access to the dynamic storage 
routines. These routines maintain a linked list of all unallocated storage. Upon request, 
these routines search for the first available segment in the free list that satisfies the 
request size, remove the requested segment, and return the remaining portion to the 
free list. If the storage is not available, the run-time system signals ERROR(7), Free 
Space Exhausted. 

PL/I dynamically allocates storage upon entry to RECURSIVE procedures, when 
processing explicit or implicit OPEN statements for files performing disk I/O, or when 
processing an ALLOCATE statement. PL/I always allocates an even number of bytes 
or whole words, no matter what the request size. 

19.1.1 The TOTWDS and MAXWDS Functions 

It is often useful to find the amount of storage available at any given point while 
the program is running. The TOTWDS (Total Words) and MAXWDS (Max Words) 
functions provide this information. 

You must declare the functions in the calling program as: 

declare totwds entry returns(fixed(15))5 
declare waxwds entry r e t u r n s ( f i x e d ( 1 5 ) ) 5 
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When you invoke the TOTWDS subroutine, it scans the free storage list and returns 
the total number of words (double bytes) available. The MAXWDS subroutine returns 
the size (in words) of the largest contiguous segment in the free list. A subsequent 
ALLOCATE statement that specifies a segment size less than or equal to MAXWDS 
does not signal ERROR(7), because at least that much storage is available. 

Both TOTWDS and MAXWDS count in word units, so the returned values can be 
held by FIXED BINARY(15) counters. Both TOTWDS and MAXWDS return the value 
-1 if they encounter invalid link words while scanning the free space list. This is usually 
due to an out-of-bounds subscript or pointer store operation. Otherwise, these functions 
return a nonnegative integer value. 

19.1.2 The ALLWDS Subroutine 

The PL/I Run-time Subroutine Library contains a subroutine, called ALLWDS, that 
you use to control the dynamic allocation size. You must declare the subroutine in the 
calling program as: 

declare a 1 1 w d s e n t r v ( f i x e d ( 1 5' ) ) returris(pointer) i 

The ALLWDS subroutine allocates a memory segment in words equal to the size 
given by the input parameter, and returns a pointer to the allocated segment. If no 
segment is available, ALLWDS signals the ERROR(7) condition. The input value must 
be a nonnegative integer. 

Listing 19-1 shows the ALLTST program which is an example of how to use the 
TOTWDS, MAXWDS, and ALLWDS functions. Listing 19-2 shows a sample inter- 
action with the ALLTST program. 
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l 

2 
3 

a 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
IB 
17 
1 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 



a 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
B c 



/#*#**#*#**#*##**###*#*#*#**###♦*###*####***###*######/ 
/* This program tests the TOTWDS , MAXWDS , and ALLWDS */ 
/* functions froM the Run-time Subroutine Library. #/■ 

•alltst: 

procedure opt i ons ( main ) 5 

declare 

totwds entry returns(fixed(15))t 

iitaxwds entry returns(fixed(15))» 

allwds ent ry ( fixed ( 15 ) ) ret u rns ( po int e r ) i 

declare 

al 1 req f ixed( 15) , 

mewpt r pt r ( 

weminx f i xed ( 15 ) » 

Memory (0:0) bit(lB) based ( mewpt r ) 5 



-do whi le ( M ' b ) i 

put edit (totwdsOt* Total Words Available'* 
maxwds()»' Maximum Segment Size') 
'Allocation Size? ') ( 2 ( sKi p >f ( 6 ) ia ) » sKi p »a ) i 
Set 1 ist ( al 1 req ) i 
memptr=allwds(allreq); 

put edi t ( 'Al located ' > a 1 1 re=i > v Words at ' tunspec (memptr)) 
(sKip»a»f (B) ta tb4) 5 

/* clear Memory as example */ 
-do Meminx = to allreq-15 

memo rv (ineminx ) = v OOOO'b45 
-end i 
end i 



-end alltst! 



Listing 19-1. The ALLTST Program 



PR£SEN1 



IE IS Pf 



TO DICH 
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f\>alltst 

24470 Total Words Available 
24470 Maximum Segment Size 
Allocation Size? 

Allocated Words at 28D6 

24468 Total Words Available 

24468 Maximum Sesment Size 
Allocation Size? 100 

Allocated 100 Words at 28DA 

2436B Total Words Available 

2436B Maximum Segment Size 
Allocation Size? 500 

Allocated 500 Words at 29AB 

23864 Total Words Available 

23864 Maximum Segment Size 
Allocation Size? 23865 

ERROR (7)> Free Space Exhausted 

TracebacK: 01GD 

A> 

Listing 19-2. Interaction with the ALLTST Program 

19.2 The STKSIZ Function 

In PL/I, the program stack is placed above the code and data area, and below the 
dynamic storage area (TPA). The default size of the program stack is 512 bytes, but 
can be changed using the STACK(n) option in the main procedure heading. 

The STKSIZ (Stack Size) function returns the current stack size in bytes. This function 
is particularly useful for checking possible stack overflow conditions, or in determining 
the maximum stack depth during program testing. 

You must declare the STKSIZ function in the calling program as: 

declare stksiz retums(fixed(15))5 

Listing 19-3 shows an example of the STKSIZ function in the program called ACKTST, 
where it checks the maximum stack depth during RECURSIVE procedure processing. 
Listing 19-4 shows an interaction with this program. 
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b 
b 
b 
b 
b 
b 
b 
b 
b 
b 

B c 
d 
d 

19 d 

20 d 

21 d 

22 d 

23 d 

24 d 

25 c 
2G b 

27 b 

28 b 

29 c 

30 c 

31 c 

32 c 

33 c 

34 c 

35 c 

36 c 

37 c 

38 c 

39 c 

40 c 

41 c 

42 c 

43 b 

44 b 



/* This program tests the STKSIZ function while #/ 
/* evaluating a RECURSIVE procedure. */ 

-ack: 

procedure options (main »stack(2000) ) ! 
declare 

(m tn ) fixed > 

(maxm imaxn ) fixed » 

ncalls decimal (B) » 

(curstack* stacKsize) fixed* 

stksiz entry returns ( f ixed ) 5 



put sKip lisU'Type max m>n: ')5 

Set list (maxm »maxn ) i 

do m = to maxm ! 

-do n = to maxn ! 

ncal 1 s = i 

curstacK = ! 

stacKsize = Oi 

put edit O Ack ( ' »m * ' »' tn > ' ) = ' >ackermann(m»n) t 
ncalls*' Cal Is » ' tstacksize » ' Stack Bytes') 
(skip»a»2(f (2) >a) »f (G) »f (7) ,a.f (4) »a) i 
-end i 
end 5 
stop ! 

i — acke rmann : 

procedure (m tn ) retu rns ( f ixed ) recursive) 

declare 

(m »n ) fixed 5 
ncalls = ncalls + 1 i 
curstack = stKsiz ( ) ! 
if curstack > stacKsize then 

stacksize = curstacK! 
if m = then 

retu rn ( n + 1 ) ! 
if n = then 

retum(acKermann(m-l tl) ) ! 
return(acKermann(m-l tackermann(mtn-l))) ! 
1 — end acke rmann ! 



-end ack ! 



Listing 19-3. The ACKTST Program 
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A>ac 


Htst 




Type 


max m »n : 


GiG 


Ack< 





0) = 


1 


AcK( 





1) = 


2 


AcK( 





2) = 


3 


AcK( 





3) = 


4 


AcK( 





4) = 


5 


Ack( 





5) = 


6 


Ack( 





6) = 


7 


Ack( 




0) = 


2 


Ack( 




i) = 


3 


Ack( 




2) = 


4 


AcK( 




3) = 


5 


Ack( 




4) = 


B 


AcK( 




5) = 


7 


Ack( 




6) = 


8 


Ack( 


2 


0) = 


3 


Ack( 


2 


1) = 


5 


Ack( 


2 


2) = 


7 


Ack( 


2 


3) = 


9 


Ack( 


2 


4) = 


11 


Ack( 


2 


5) = 


13 


Ack( 


? 


G) = 


15 


Ack( 


3 


0) = 


5 


Ack( 


3 


1) = 


13 


Ack ( 


3 


2) = 


29 


Ack( 


3 


3) = 


61 


Ack( 


3 


4) = 


125 


Ack( 


3 


5) = 





1 


Cal 


Is t 


1 


Cal 


1 5 t 


1 


Cal 


Is t 


1 


Cal 


1 5 t 


1 


Cal 


1 S I 


1 


Cal 


1 5 t 


1 


Cal 


Is I 


2 


Cal 


Is t 


4 


Cal 


1 S 1 


6 


Cal 


1 5 t 


8 


Cal 


1 5 > 


10 


Cal 


1 5 1 


12 


Cal 


1 S t 


14 


Cal 


1 S 1 


5 


Cal 


1 S 1 


14 


Cal 


1 S t 


27 


Cal 


1 5 » 


44 


Cal 


1 5 1 


65 


Cal 


1 5 t 


90 


Cal 


1 S > 


119 


Cal 


Is t 


15 


Cal 


1 5 » 


106 


Cal 


Is 1 


541 


Cal 


1 S t 


2432 


Cal 


1 S » 


10307 


Cal 


1 S t 



4 


Stack 


Bvtes 


4 


Stack 


Bytes 


4 


Stack 


Bytes 


4 


Stack 


Bytes 


4 


Stack 


Bytes 


4 


Stack 


Bytes 


4 


Stack 


Bytes 


6 


Stack 


Bytes 


8 


Stack 


Bytes 


10 


Stack 


Bytes 


12 


Stack 


Bytes 


14 


Stack 


Bytes 


16 


Stack 


Bytes 


18 


Stack 


Bytes 


10 


Stack 


Bytes 


14 


Stack 


Bytes 


18 


Stack 


Bytes 


22 


Stack 


Bytes 


26 


Stack 


Bytes 


30 


Stack 


Bytes 


34 


Stack 


Bytes 


16 


Stack 


Bytes 


32 


Stack 


Bytes 


64 


Stack 


Bytes 


128 


Stack 


Bytes 


256 


Stack 


Bytes 



Listing 19-4. Output From the ACKTST Program 



End of Section 1 9 
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Section 20 
Overlays 



This section describes how to use the linkage editor to create PL/I overlays. Overlays 
are programs comprised of separate files. The advantage of overlays is that they share 
the same memory locations, so you can write large programs that run in a limited 
memory environment. 



20.1 Using Overlays in PL/I 

In both the 8080 and 8086 implementations, the size of the Transient Program Area 
(TPA) determines the upper limit on the size of a program. However, there is another 
constraint in the 8086 implementation. Although there can be enough memory space 
available on the system, the Compiler generates code that assumes the Small memory 
model. The Small model means that when you link one or more OBJ files with the 
Run-time Subroutine Library (RSL), the size of the code and data sections in the CMD 
are each limited to 64K. Thus, the Compiler determines the upper limit on the size of 
any program, but the size limit is not encountered until link time. 

With modular design, you can write a large program that does not need to reside 
in memory all at once. For example, many application programs are menu-driven, in 
which the user selects one of a number of functions to perform. Because the functions 
are separate and invoked sequentially, they do not need to reside in memory simul- 
taneously. When one of the functions is complete, control returns to the menu portion 
of the program, from which the user selects the next function. Using overlays, you can 
divide such a program into separate subprograms that can be stored on disk and loaded 
only when required. 
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The following figure illustrates the concept of overlays. Suppose a menu-driven 
application program consists of three separate user-selected functions. If each function 
requires 3 OK of memory, and the menu portion requires 10K, then the total memory 
required for the program is 100K, as shown in Figure 20- la. However, if the three 
functions are designed as overlays, as shown in Figure 20- lb, the program requires 
only 40K, because all three functions share the same memory locations. 



Function 
3 



Function 
2 



Function 
1 



Menu 



30K 



30K 



30K 



10K 



100K 



30K 



40K 



10K 



Function 
1 




Function 
2 




Function 
3 


























Menu 



20-la. Without Overlays 20-lb. Separate Overlays 

Figure 20-1. Using Overlays in a Large Program 

You can also create nested overlays in the form of a tree structure, where each overlay 
can call other overlays up to a maximum nesting level that the Overlay Manager 
determines. Section 20. 3 describes the command line syntax for creating nested overlays. 
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20.1 Using Overlays in PL/I 



Figure 20-2 illustrates the tree structure of overlays. The top of the highest overlay 
determines the total amount of memory required. In Figure 20-2, the highest overlay 
is SUB4. This is substantially less memory than would be required if all the functions 
and subfunctions had to reside in memory simultaneously. 
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Figure 20-2. Tree Structure of Overlays 



20.2 Writing Overlays in PL/I 

There are two ways to write PL/I programs that use overlays. The first method 
involves no special coding, but has two restrictions. The first restriction is all that 
overlays must be on the default drive; the second is that the overlay names must be 
determined at translation time and cannot be changed at run-time. 

The second method requires a more involved calling sequence, but does not have 
either of the restrictions of the first method. 
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20.2.1 Overlay Method One 

To use the first method, you declare an overlay as an entry constant in the module 
where it is referenced. As an entry constant, the overlay can have parameters declared 
in a parameter list. The overlay itself is simply a PL/I procedure or group of procedures. 

For example, the following program is a root module with one overlay: 

root: 

procedure options(main) 5 

declare 

o V 1 a y 1 e n t r >' ( c h a r a c t e r ( 1 5 ) ) 5 

put skip list( v root')5 

call o u 1 a y 1 ( x o u e r 1 a y 1 ' ) 5 
end root? 

The overlay OVLAY1.PLI is defined as follows: 

o v 1 a y 1 ; 

procedure(c) 5 

declare 

c cha rac t e r ( 15 ) ? 

put skip list(c)5 
e n d o v 1 a y 1 5 

Note: when passing parameters to an overlay, you must ensure that the number and 
type of the parameters are the same in both the calling program and the overlay. 

When the program runs, ROOT first displays the message 'root' at the console. The 
CALL statement then transfers control to the Overlay Manager. The Overlay Manager 
loads the file OVLAY1 from the default drive and transfers control to it. 

When the overlay receives control, it displays the message 'overlay 1' at the console. 
OVLAY1 then returns control directly to the statement following the CALL statement 
in ROOT. The program then continues from that point. 

If the requested overlay is already in memory, the Overlay Manager does not reload it 
before transferring control. 
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The following constraints apply to overlay method one: 

■ The label in the call statement is the actual name of the overlay file loaded by the 
Overlay Manager; consequently, the two names must agree. 

■ The name of the entry point to an overlay need not agree with the name used 
in the calling sequence, but using the same name avoids confusion. 

■ The Overlay Manager only loads overlays from the drive that was the default 
when the root module began execution. The Overlay Manager disregards any 
changes in the default drive that occur after the root module begins execution. 

■ The names of the overlays are fixed. To change the names of the overlays, you 
must edit, recompile, and relink the program. 

■ No nonstandard PL/I statements are needed. Thus, you can postpone the deci- 
sion on whether or not to create overlays until link time. 

20.2.2 Overlay Method Two 

In some applications, you might want to have greater flexibility with overlays, such 
as loading overlays from different drives, or determining the name of an overlay from 
the console or a disk file at run-time. 

To do this, a PL/I program must declare an explicit entry point into the Overlay 
Manager, as follows: 

declare ? o u 1 a v e n t r v ( c h a r a c t e r ( 1 ) t f i x e d ( 1 ) ) 5 

This entry point requires two parameters. The first is a 10-character string that 
specifies the name of the overlay to load, and an optional drive code in the standard 
format (d:filename). 

The second parameter is the Load Flag. If the Load Flag is 1, the Overlay Manager 
loads the specified overlay whether or not it is already in memory. If the Load Flag is 0, 
the overlay manager loads the overlay only if it is not already in memory. 
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Using this method, the example illustrating method one appears as follows: 

roo t : 

procedure options(wain) ! 
declare 

? o v 1 a y entry (character( 10) * f i x e d ( 1 ) ) t 

dummy e n t r y ( c h a r a c t e r ( 1 5 ) ) * 

name c h a r a c t e r ( 1 ) 5 

put s Kip list( x root')5 
name = N 0U1 ' 5 
call ? o v 1 a y ( n a m e > ) 5 
call d u m m y( 'overlay 1 ' ) 5 
end root! 

The file OV1.PLI is the same as the previous example. 

At run-time, the statement 

call ? o v 1 a v ( n a m e » ) 5 

directs the Overlay Manager to load OV1 from the default drive (1 is the current value of 
the variable name); control then transfers to OV1. When OV1 finishes processing, 
control returns to the statement following the invocation. 

In this example, the variable name is assigned the value 'OV1'. However, you could 
also supply the overlay name as a character string from some other source, such as 
the console keyboard. 

The following constraints apply to overlay method two: 

■ You can specify a drive code so the Overlay Manager can load overlays from 
drives other than the default drive. If you do not specify a drive code, the 
Overlay Manager uses the default drive as described in method one. 

■ If you pass any parameters to the overlay, they must agree in number and type 
with the parameters that the overlay expects. 
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20.2.3 General Overlay Constraints 

The following general constraints apply when creating overlays in a PL/I program: 



■ Each overlay has only one entry point. The Overlay Manager in the PL/I Run- 
time Subroutine Library assumes that this entry point is at the load address of 
the overlay. 

■ You cannot make an upward reference from a module to entry points in overlays 
higher on the tree. The only exception is a reference to the main entry point of 
the overlay. You can make downward references to entry points in overlays 
lower on the tree or in the root module. 

■ Common segments (EXTERNALS in PL/I) that are declared in one module 
cannot be initialized by a module higher in the tree. The linkage editor ignores 
any attempt to do so. 

■ You can nest overlays to a depth of five levels. 

■ The Overlay Manager uses the default buffer located at 80H, so user programs 
should not depend on data stored in this buffer. Note that in the 8086 implemen- 
tation, the default buffer is at 80H relative to the base of the Data segment. 

20.3 Command Line Syntax 

To specify overlays in the command line of the linkage editor, enclose each overlay 
specification in parentheses. You can create overlays with LINK-80 in one of the 
following forms: 

link root(ovl) 

link root(ovl,part2,part3) 

link root(ovl =partl,part2,part3) 

The first form produces the file OVl.OVL from the file OV1.REL. The second form 
produces the file OVl.OVL from OV1.REL, PART2.REL, and PART3.REL. The third 
form produces the file OVl.OVL from PART1.REL, PART2.REL, and PART3.REL. 
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Create overlays with LINK-86 using the same forms: 

Hnk86 root(ovl) 

Hnk86 root(ovl,part2,part3) ^ 

link86 root(ovl = parti, part2,part3) 

The first form produces the file OVl.OVR from the file OVl.OBJ. The second form 
produces the file OVl.OVR from OVl.OBJ, PART2.0BJ, and PART3.0BJ. The third 
form produces the file OVl.OVR from PARTI. OBJ, PART2.0BJ, and PART3.0BJ. 

In the command line, a left parenthesis indicates the start of a new overlay specifi- 
cation, and also indicates the end of the group preceding it. All files to be included at 
any point on the tree must appear together, without any intervening overlay specifi- 
cations. You can use spaces to improve readability, but do not use commas to set off 
the overlay specifications from the root module or from each other. 

For example, the following command line is invalid: 

A > I i n K root ( ovl ) tmo re root 

The correct command is as follows: 

A > J inH roattmoreroot(ovl) 

To nest overlays, you must specify them in the command line with nested parentheses. 
For example, the following command line creates the overlay system shown in Figure 
20-2: 

A>IinK meriu( fund (subl ) (sub 2) ) (funcZ) (func3 (sub3) (subA 

End of Section 20 
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